Transparency Laws API

1
import { HoleFoundationClient } from '@hole-foundation/sdk';
2
3
const client = new HoleFoundationClient({
4
  environment: 'https://api.theholefoundation.org',
5
  token: 'your-jwt-token'
6
});
7
8
const jurisdictions = await client.transparency.listJurisdictions({
9
  limit: 52
10
});
11
12
jurisdictions.forEach(j => {
13
  console.log(`${j.name} (${j.code})`);
14
  console.log(`  Type: ${j.type}`);
15
  console.log(`  Statutes: ${j.statute_count}`);
16
});

1
// Get all states
2
const states = await client.transparency.listJurisdictions({
3
  type: 'state',
4
  limit: 51  // 50 states + DC
5
});
6
7
// Get federal only
8
const federal = await client.transparency.listJurisdictions({
9
  type: 'federal',
10
  limit: 1
11
});

1
const rights = await client.transparency.searchRights({
2
  query: 'public records',
3
  jurisdiction: 'california',
4
  limit: 20
5
});
6
7
rights.forEach(right => {
8
  console.log(right.title);
9
  console.log(`  Citation: ${right.citation}`);
10
  console.log(`  Summary: ${right.summary}`);
11
});

1
const right = await client.transparency.getRight('right-123');
2
3
console.log(right.title);
4
console.log(right.full_text);
5
console.log('Applies to:', right.applies_to);
6
console.log('Deadlines:', right.deadlines);

1
const meetingRights = await client.transparency.searchRights({
2
  query: 'meetings',
3
  category: 'open_meetings',
4
  limit: 50
5
});
6
7
const recordsRights = await client.transparency.searchRights({
8
  query: 'records',
9
  category: 'public_records',
10
  limit: 50
11
});

1
const exemptions = await client.transparency.searchExemptions({
2
  query: 'privacy',
3
  jurisdiction: 'federal',
4
  limit: 20
5
});
6
7
exemptions.forEach(ex => {
8
  console.log(ex.title);
9
  console.log(`  Citation: ${ex.citation}`);
10
  console.log(`  Category: ${ex.category}`);
11
  console.log(`  Summary: ${ex.summary}`);
12
});

1
// Get all privacy exemptions
2
const privacy = await client.transparency.searchExemptions({
3
  category: 'personal_information',
4
  limit: 100
5
});
6
7
// Get national security exemptions
8
const security = await client.transparency.searchExemptions({
9
  category: 'national_security',
10
  limit: 50
11
});

1
const exemption = await client.transparency.getExemption('exemption-456');
2
3
console.log(exemption.title);
4
console.log(exemption.full_text);
5
console.log('Category:', exemption.category);
6
console.log('Jurisdiction:', exemption.jurisdiction);

1
const statute = await client.transparency.getStatute('5-USC-552');
2
3
console.log(statute.title);
4
console.log(statute.citation);
5
console.log(statute.full_text);
6
console.log('Jurisdiction:', statute.jurisdiction);
7
console.log('Effective date:', statute.effective_date);

1
async function compareRights(states: string[], query: string) {
2
  const comparisons = await Promise.all(
3
    states.map(async state => {
4
      const rights = await client.transparency.searchRights({
5
        query,
6
        jurisdiction: state,
7
        limit: 10
8
      });
9
      return { state, count: rights.length, rights };
10
    })
11
  );
12
13
  return comparisons;
14
}
15
16
// Compare public records laws
17
const comparison = await compareRights(
18
  ['california', 'texas', 'florida'],
19
  'public records deadlines'
20
);
21
22
comparison.forEach(c => {
23
  console.log(`${c.state}: ${c.count} rights found`);
24
});

1
async function findExemptions(query: string) {
2
  const allJurisdictions = await client.transparency.listJurisdictions({
3
    limit: 52
4
  });
5
6
  const exemptionsByJurisdiction = await Promise.all(
7
    allJurisdictions.map(async j => {
8
      const exemptions = await client.transparency.searchExemptions({
9
        query,
10
        jurisdiction: j.code,
11
        limit: 100
12
      });
13
      return {
14
        jurisdiction: j.name,
15
        count: exemptions.length,
16
        exemptions
17
      };
18
    })
19
  );
20
21
  // Sort by most exemptions
22
  return exemptionsByJurisdiction
23
    .sort((a, b) => b.count - a.count);
24
}
25
26
const analysis = await findExemptions('law enforcement');
27
console.log('Most law enforcement exemptions:');
28
analysis.slice(0, 10).forEach(a => {
29
  console.log(`  ${a.jurisdiction}: ${a.count} exemptions`);
30
});

1
interface Jurisdiction {
2
  id: string;
3
  name: string;          // "California"
4
  code: string;          // "california"
5
  type: string;          // "state" or "federal"
6
  abbreviation: string;  // "CA"
7
  statute_count: number;
8
  metadata: {
9
    population?: number;
10
    capital?: string;
11
    website?: string;
12
  };
13
}

1
interface RightOfAccess {
2
  id: string;
3
  title: string;
4
  citation: string;
5
  summary: string;
6
  full_text: string;
7
  jurisdiction: string;
8
  category: string;
9
  applies_to: string[];
10
  deadlines?: {
11
    response_time: string;
12
    appeal_time: string;
13
  };
14
  fees?: {
15
    permitted: boolean;
16
    limits?: string;
17
  };
18
  metadata: Record<string, any>;
19
}

1
interface Exemption {
2
  id: string;
3
  title: string;
4
  citation: string;
5
  summary: string;
6
  full_text: string;
7
  jurisdiction: string;
8
  category: string;
9
  scope: 'mandatory' | 'discretionary';
10
  case_law?: Array<{
11
    citation: string;
12
    summary: string;
13
    year: number;
14
  }>;
15
  metadata: Record<string, any>;
16
}

1
async function buildJurisdictionGuide(jurisdiction: string) {
2
  // Get jurisdiction info
3
  const jurisdictions = await client.transparency.listJurisdictions({
4
    limit: 52
5
  });
6
  const info = jurisdictions.find(j => j.code === jurisdiction);
7
8
  // Get all rights
9
  const rights = await client.transparency.searchRights({
10
    jurisdiction,
11
    limit: 100
12
  });
13
14
  // Get all exemptions
15
  const exemptions = await client.transparency.searchExemptions({
16
    jurisdiction,
17
    limit: 100
18
  });
19
20
  return {
21
    jurisdiction: info,
22
    rights,
23
    exemptions,
24
    summary: {
25
      total_rights: rights.length,
26
      total_exemptions: exemptions.length,
27
      categories: {
28
        rights: [...new Set(rights.map(r => r.category))],
29
        exemptions: [...new Set(exemptions.map(e => e.category))]
30
      }
31
    }
32
  };
33
}
34
35
const guide = await buildJurisdictionGuide('california');
36
console.log(JSON.stringify(guide, null, 2));

1
async function getDeadlines(jurisdiction: string) {
2
  const rights = await client.transparency.searchRights({
3
    query: 'deadlines',
4
    jurisdiction,
5
    limit: 50
6
  });
7
8
  const withDeadlines = rights.filter(r => r.deadlines);
9
10
  return withDeadlines.map(r => ({
11
    title: r.title,
12
    citation: r.citation,
13
    response_time: r.deadlines.response_time,
14
    appeal_time: r.deadlines.appeal_time
15
  }));
16
}
17
18
const deadlines = await getDeadlines('federal');
19
deadlines.forEach(d => {
20
  console.log(`${d.title}:`);
21
  console.log(`  Response: ${d.response_time}`);
22
  console.log(`  Appeal: ${d.appeal_time}`);
23
});

1
async function analyzeFees(jurisdiction: string) {
2
  const rights = await client.transparency.searchRights({
3
    query: 'fees',
4
    jurisdiction,
5
    limit: 100
6
  });
7
8
  const feeStats = {
9
    with_fees: rights.filter(r => r.fees?.permitted).length,
10
    without_fees: rights.filter(r => !r.fees?.permitted).length,
11
    fee_limits: rights
12
      .filter(r => r.fees?.limits)
13
      .map(r => ({ title: r.title, limits: r.fees.limits }))
14
  };
15
16
  return feeStats;
17
}
18
19
const fees = await analyzeFees('texas');
20
console.log('Fee structure:', fees);

1
import { TheholetruthApiError } from '@hole-foundation/sdk';
2
3
try {
4
  const rights = await client.transparency.searchRights({
5
    query: 'public records',
6
    jurisdiction: 'invalid-jurisdiction'
7
  });
8
} catch (error) {
9
  if (error instanceof TheholetruthApiError) {
10
    if (error.status === 404) {
11
      console.error('Jurisdiction not found');
12
    } else if (error.status === 400) {
13
      console.error('Invalid query parameters');
14
    }
15
  }
16
  throw error;
17
}