legiscan-ts 3.0.0 → 3.0.1

package/README.md

@@ -39,13 +39,30 @@ The client provides async methods corresponding to each API call. For example, t
 ```js
 let results = await client.getSearch("education AND javascript");
 for (let result of results) {
-  let details = await client.getBill(result.bill_id);
-  Object.assign(result, details);
+	let details = await client.getBill(result.bill_id);
+	Object.assign(result, details);
 }
 ```
 
 Generally, the objects returned by the client methods will match the schema described in the [API documentation](https://legiscan.com/misc/LegiScan_API_User_Manual.pdf), but with some normalization applied. For example, when calling `getBill`, the status, event, and sponsor type fields will be normalized to their string representations, with an added `*_id` property containing the numerical code. This is meant to create more consistency between API calls, some of which return flags as strings and some as numerical codes.
 
+## Response schemas
+
+The package exports the Zod schemas used to validate the client's normalized responses, such as `zGetBill`, `zGetSearch`, and `zGetSessionList`. You can use their Zod APIs to validate stored responses or compose your own schemas:
+
+```ts
+import { zGetBill, type Bill } from "@ryangarber/legiscan-ts";
+import { z } from "zod";
+
+const bill = zGetBill.parse(savedResponse);
+const summarySchema = zGetBill.pick({ bill_id: true, title: true });
+type Summary = z.infer<typeof summarySchema>;
+```
+
+Field descriptions are available at runtime through `.description` and in IntelliSense on schema properties, parsed results, and inferred types. Response types such as `Bill` are inferred directly from these schemas, and the client uses those same types for its return values.
+
+These schemas describe the normalized client results. Raw LegiScan API responses may need the conversions performed by the client before they can be parsed.
+
 # CLI
 
 When installed globally, or when executed from an `npm run` script, the `legiscan` command provides [ND-JSON](https://github.com/ndjson/ndjson-spec) output from API calls. Some of these calls return a lot of results, or need to be filtered, and that's easier to do with newline-delimited output in languages and tools that support streaming from invoked processes.
@@ -84,13 +101,13 @@ var hash = bill.change_hash;
 
 var details = db.data.cache[hash];
 if (details) {
-  // use the cached info
-  details = JSON.parse(details);
+	// use the cached info
+	details = JSON.parse(details);
 } else {
-  // get a fresh copy and cache it
-  details = await client.getBill(bill.bill_id);
-  db.data.cache[hash] = JSON.stringify(details);
-  await db.write();
+	// get a fresh copy and cache it
+	details = await client.getBill(bill.bill_id);
+	db.data.cache[hash] = JSON.stringify(details);
+	await db.write();
 }
 ```
 

package/dist/cli.mjs

@@ -319,7 +319,7 @@ const BillType = {
 	Remonstration: 22,
 	CommitteeBill: 23
 };
-const Vote = {
+const VoteType = {
 	Yea: 1,
 	Nay: 2,
 	Abstain: 3,
@@ -399,9 +399,8 @@ function zNames(haystack) {
 function zNumbers(haystack) {
 	return z.union(Object.values(haystack).map((n) => z.literal(n)));
 }
-// src/schemas/types.ts
-/** @public */
-const _zSession = z.object({
+// src/types.ts
+const SessionSchema = z.object({
 	session_id: z.number().describe("Internal session id"),
 	session_name: z.string().describe("State specific session name"),
 	session_title: z.string().describe("Normalized session title with year(s) and Regular/Nth Special Session"),
@@ -415,13 +414,11 @@ const _zSession = z.object({
 	prior: z.boolean().describe("Flag for session being archived"),
 	sine_die: z.boolean().describe("Flag for session being adjourned sine die")
 });
-/** @public */
-const zGetSessionList = z.array(_zSession.extend({
+const SessionListSchema = z.array(SessionSchema.extend({
 	session_hash: z.hash("md5").nullable().describe("Hash of session data, used for caching"),
 	dataset_hash: z.hash("md5").nullable().describe("Hash of entire dataset, used for caching")
 }));
-/** @public */
-const _zBillText = z.object({
+const BillTextSchema = z.object({
 	doc_id: z.number().describe("Internal document id"),
 	bill_id: z.number().optional().describe("Internal bill id"),
 	type: zNames(TextType).describe("Type of draft text"),
@@ -441,38 +438,30 @@ const _zBillText = z.object({
 	alt_mime_raw: z.string().nullable().describe("Raw MIME type of the alternate document, e.g. 'application/pdf'"),
 	alt_state_link: z.url().nullable().describe("URL of alternate document on state website"),
 	alt_text_size: z.number().nullable().describe("Size in bytes of the decoded BASE64 alternate document (add 33% for base64)"),
-	alt_text_hash: z.hash("md5").nullable().describe("MD5 hash of the decoded BASE64 alternate document")
+	alt_text_hash: z.hash("md5").nullable().describe("MD5 hash of the decoded BASE64 alternate document"),
+	doc: z.base64().describe("BASE64 encoded document").nullish(),
+	alt_doc: z.base64().describe("BASE64 encoded alternate document").nullish()
 });
-/** @public */
-const zGetBillText = _zBillText.extend({
-	doc: z.base64().describe("BASE64 encoded document"),
-	alt_doc: z.unknown()
-});
-/** @public */
-const _zCommittee = z.object({
+const CommitteeSchema = z.object({
 	committee_id: z.number().describe("Internal committee id"),
 	chamber_raw: z.string().describe("Internal chamber name, e.g. 'S' or 'H'"),
 	chamber_id: z.number().describe("Internal chamber id"),
 	name: z.string().describe("Committee name")
 });
-/** @public */
-const _zCommitteeReferral = z.intersection(_zCommittee, z.object({ date: z.iso.date().describe("Date of referral") }));
-/** @public */
-const _zBillProgress = z.object({
+const CommitteeReferralSchema = z.intersection(CommitteeSchema, z.object({ date: z.iso.date().describe("Date of referral") }));
+const BillProgressSchema = z.object({
 	date: z.iso.date().describe("Date of progress event"),
 	event: zNames(Progress).describe("Normalized progress event"),
 	event_id: zNumbers(Progress).describe("Internal progress event id")
 });
-/** @public */
-const _zBillHistory = z.object({
+const BillHistorySchema = z.object({
 	date: z.iso.date().describe("Date of action"),
 	action: z.string().describe("Description of action taken"),
 	chamber_raw: z.string().nullable().describe("Internal chamber name"),
 	chamber_id: z.number().nullable().describe("Internal chamber id"),
 	importance: z.boolean().describe("Flag for major steps (i.e. those included in progress list)")
 });
-/** @public */
-const _zPerson = z.object({
+const PersonSchema = z.object({
 	people_id: z.number().describe("Internal person id"),
 	person_hash: z.string().describe("Hash of the person's details, used for caching"),
 	party: zNames(Party).describe("Normalized party, e.g. 'Democrat' or 'Republican'"),
@@ -501,23 +490,18 @@ const _zPerson = z.object({
 	state_federal: z.unknown(),
 	bio: z.unknown()
 });
-/** @public */
-const zGetPerson = _zPerson.extend({});
-/** @public */
-const _zSast = z.object({
+const SastSchema = z.object({
 	type: zNames(SastType).describe("Normalized sast type"),
 	type_id: zNumbers(SastType).describe("Internal sast id"),
 	type_raw: z.string().describe("Internal sast type name"),
 	sast_bill_number: z.string().describe("Bill number of the sast, e.g. HB 1234"),
 	sast_bill_id: z.number().describe("Internal bill id of the sast")
 });
-/** @public */
-const _zSubject = z.object({
+const SubjectSchema = z.object({
 	subject_id: z.number().describe("Internal subject id"),
 	subject_name: z.string().describe("Name of the subject")
 });
-/** @public */
-const _zVote = z.object({
+const VoteSchema = z.object({
 	roll_call_id: z.number().describe("Internal roll call id"),
 	date: z.iso.date().describe("Date of the vote"),
 	description: z.string().describe("Description of the vote"),
@@ -530,8 +514,7 @@ const _zVote = z.object({
 	chamber_id: z.number().describe("Internal chamber id"),
 	chamber_raw: z.string().describe("Internal chamber name, e.g. 'S' or 'H'")
 });
-/** @public */
-const _zAmendment = z.object({
+const AmendmentSchema = z.object({
 	amendment_id: z.number().describe("Internal amendment id"),
 	adopted: z.boolean().describe("Flag for whether the amendment was adopted"),
 	chamber_id: z.number().describe("Internal chamber id"),
@@ -552,16 +535,12 @@ const _zAmendment = z.object({
 	alt_mime_raw: z.string().nullable().describe("Raw MIME type of the alternate document, e.g. 'application/pdf'"),
 	alt_state_link: z.url().nullable().describe("URL of the alternate document on state website"),
 	alt_amendment_size: z.number().nullable().describe("Size in bytes of the decoded alternate BASE64 document (add 33% for base64)"),
-	alt_amendment_hash: z.hash("md5").nullable().describe("MD5 hash of the decoded alternate BASE64 document")
-});
-/** @public */
-const zGetAmendment = _zAmendment.extend({
-	bill_id: z.number().describe("Internal bill id the amendment belongs to"),
-	doc: z.base64().describe("BASE64 encoded document"),
-	alt_doc: z.base64().nullable().describe("BASE64 encoded alternate document")
+	alt_amendment_hash: z.hash("md5").nullable().describe("MD5 hash of the decoded alternate BASE64 document"),
+	bill_id: z.number().describe("Internal bill id the amendment belongs to").nullish(),
+	doc: z.base64().describe("BASE64 encoded document").nullish(),
+	alt_doc: z.base64().nullable().describe("BASE64 encoded alternate document").nullish()
 });
-/** @public */
-const _zSupplement = z.object({
+const SupplementSchema = z.object({
 	supplement_id: z.number().describe("Internal supplement id"),
 	date: z.iso.date().nullable().describe("Date of the supplement"),
 	type: zNames(SupplementType).describe("Normalized supplement type"),
@@ -580,16 +559,12 @@ const _zSupplement = z.object({
 	alt_mime_raw: z.string().nullable().describe("Raw MIME type of the alternate document, e.g. 'application/pdf'"),
 	alt_state_link: z.url().nullable().describe("URL of the alternate document on state website"),
 	alt_supplement_size: z.number().nullable().describe("Size in bytes of the decoded alternate BASE64 document (add 33% for base64)"),
-	alt_supplement_hash: z.hash("md5").nullable().describe("MD5 hash of the decoded alternate BASE64 document")
+	alt_supplement_hash: z.hash("md5").nullable().describe("MD5 hash of the decoded alternate BASE64 document"),
+	bill_id: z.number().describe("Internal bill id the supplement belongs to").nullish(),
+	doc: z.base64().describe("BASE64 encoded document").nullish(),
+	alt_doc: z.base64().nullable().describe("BASE64 encoded alternate document").nullish()
 });
-/** @public */
-const zGetSupplement = _zSupplement.extend({
-	bill_id: z.number().describe("Internal bill id the supplement belongs to"),
-	doc: z.base64().describe("BASE64 encoded document"),
-	alt_doc: z.base64().nullable().describe("BASE64 encoded alternate document")
-});
-/** @public */
-const _zEvent = z.object({
+const EventSchema = z.object({
 	type: zNames(EventType).describe("Normalized event type"),
 	type_id: zNumbers(EventType).describe("Internal event type id"),
 	type_raw: z.string().describe("Internal event type name"),
@@ -598,8 +573,7 @@ const _zEvent = z.object({
 	location: z.string().nullable().describe("Location of the event (if available)"),
 	description: z.string().describe("Description of the event")
 });
-/** @public */
-const _zBill = z.object({
+const BillBaseSchema = z.object({
 	bill_id: z.number().describe("Internal bill id"),
 	bill_number: z.string().describe("Bill number, e.g. HB 1234"),
 	title: z.string().describe("Official bill title"),
@@ -610,43 +584,40 @@ const _zBill = z.object({
 	status_date: z.iso.date().nullable().describe("Date of last progress update (if available)"),
 	change_hash: z.hash("md5").describe("Hash of bill data, used for caching")
 });
-/** @public */
-const _zBillWithAction = _zBill.extend({
+const MasterListSchema = z.array(BillBaseSchema.extend({
 	last_action: z.string().nullable().describe("Description of the bill's last action (if available)"),
 	last_action_date: z.iso.date().nullable().describe("Date of the bill's last action (if available)")
-});
-const zGetMasterList = z.array(_zBillWithAction);
-z.array(_zBillWithAction.extend({
+}));
+const SearchSchema = z.array(BillBaseSchema.extend({
 	relevance: z.number().describe("Relevance score of the search result"),
 	state: zNames(State).describe("Normalized state"),
 	state_id: zNumbers(State).describe("Internal state id"),
 	bill_id: z.number().describe("Internal bill id"),
 	text_url: z.url().describe("URL of the bill text on legiscan.com"),
-	research_url: z.url().describe("URL of the bill research page on legiscan.com")
+	research_url: z.url().describe("URL of the bill research page on legiscan.com"),
+	last_action: z.string().nullable().describe("Description of the bill's last action (if available)"),
+	last_action_date: z.iso.date().nullable().describe("Date of the bill's last action (if available)")
 }).omit({
 	description: true,
 	status: true,
 	status_id: true,
 	status_date: true
 }));
-/** @public */
-const _zBillVote = _zVote.extend({
+const BillVoteSchema = VoteSchema.extend({
 	url: z.url().describe("URL of the vote on legiscan.com"),
 	state_link: z.url().describe("URL of the vote on state website")
 });
-/** @public */
-const _zSponsor = _zPerson.extend({
+const SponsorSchema = PersonSchema.extend({
 	sponsor_type: zNames(SponsorType).describe("Normalized sponsor type"),
 	sponsor_type_id: zNumbers(SponsorType).describe("Internal sponsor type id"),
 	sponsor_order: z.number().describe("Order of sponsorship")
 });
-/** @public */
-const zGetBill = _zBill.extend({
+const BillSchema = BillBaseSchema.extend({
 	session_id: z.number().describe("Internal session id"),
-	session: _zSession.describe("Session object"),
+	session: SessionSchema.describe("Session object"),
 	state_link: z.url().describe("URL of bill on state website"),
 	completed: z.boolean().describe("Flag for whether bill is completed"),
-	progress: z.array(_zBillProgress).describe("Major history of the bill (i.e. important items from history)"),
+	progress: z.array(BillProgressSchema).describe("Major history of the bill (i.e. important items from history)"),
 	state: zNames(State).describe("Normalized state"),
 	state_id: zNumbers(State).describe("Internal state id"),
 	state_raw: z.string().describe("Internal state name"),
@@ -658,37 +629,33 @@ const zGetBill = _zBill.extend({
 	current_body_id: z.number().nullable().describe("Internal body id (current)"),
 	current_body_raw: z.string().nullable().describe("Internal body name (current)"),
 	pending_committee_id: z.number().describe("Internal committee id"),
-	committee: z.array(_zCommittee).describe("List of committees if pending"),
-	referrals: z.array(_zCommitteeReferral).describe("History of committee referrals"),
-	history: z.array(_zBillHistory).describe("Full history of the bill"),
-	sponsors: z.array(_zSponsor).describe("Sponsors of the bill"),
-	sasts: z.array(_zSast).describe("SASTs of the bill"),
-	subjects: z.array(_zSubject).describe("Subjects of the bill"),
-	texts: z.array(_zBillText).describe("Documents from the bill"),
-	votes: z.array(_zBillVote).describe("Votes for the bill"),
-	amendments: z.array(_zAmendment).describe("Amendments to the bill"),
-	supplements: z.array(_zSupplement).describe("Supplements to the bill"),
-	calendar: z.array(_zEvent).describe("Events related to the bill")
+	committee: z.array(CommitteeSchema).describe("List of committees if pending"),
+	referrals: z.array(CommitteeReferralSchema).describe("History of committee referrals"),
+	history: z.array(BillHistorySchema).describe("Full history of the bill"),
+	sponsors: z.array(SponsorSchema).describe("Sponsors of the bill"),
+	sasts: z.array(SastSchema).describe("SASTs of the bill"),
+	subjects: z.array(SubjectSchema).describe("Subjects of the bill"),
+	texts: z.array(BillTextSchema).describe("Documents from the bill"),
+	votes: z.array(BillVoteSchema).describe("Votes for the bill"),
+	amendments: z.array(AmendmentSchema).describe("Amendments to the bill"),
+	supplements: z.array(SupplementSchema).describe("Supplements to the bill"),
+	calendar: z.array(EventSchema).describe("Events related to the bill")
 });
-/** @public */
-const _zRollCallVote = z.object({
+const RollCallVoteSchema = z.object({
 	people_id: z.number().describe("Internal person id"),
-	vote: zNames(Vote).describe("Vote of the person"),
-	vote_id: zNumbers(Vote).describe("Internal vote id"),
+	vote: zNames(VoteType).describe("Vote of the person"),
+	vote_id: zNumbers(VoteType).describe("Internal vote id"),
 	vote_raw: z.string().describe("Internal vote name")
 });
-/** @public */
-const zGetRollCall = _zVote.extend({
+const RollCallSchema = VoteSchema.extend({
 	bill_id: z.number().describe("Internal bill id the vote belongs to"),
-	votes: z.array(_zRollCallVote).describe("Individual votes for the roll call")
+	votes: z.array(RollCallVoteSchema).describe("Individual votes for the roll call")
 });
-/** @public */
-const zGetSessionPeople = z.array(_zPerson.extend({}));
-/** @public */
-const zGetSponsoredList = z.array(z.object({
+const SessionPeopleSchema = z.array(PersonSchema.extend({}));
+const SponsoredListSchema = z.array(z.object({
 	bill_id: z.number().describe("Internal bill id"),
 	bill_number: z.string().describe("Bill number, e.g. HB 1234"),
-	session: _zSession
+	session: SessionSchema
 }));
 // src/client.ts
 /**
@@ -740,7 +707,7 @@ var LegiscanClient = class {
 	*/
 	async getSessionList({ state }) {
 		const { sessions } = await this.request("getSessionList", { ...state ? { state: asName(State, state) } : {} });
-		return zGetSessionList.parse(sessions.map((s) => ({
+		return SessionListSchema.parse(sessions.map((s) => ({
 			session_id: s.session_id,
 			state: asName(State, s.state_id),
 			state_id: s.state_id,
@@ -768,7 +735,7 @@ var LegiscanClient = class {
 			...state ? { state: asName(State, state) } : {},
 			...session ? { id: session.toString() } : {}
 		});
-		return zGetMasterList.parse(numericalToArray(masterlist).map((b) => ({
+		return MasterListSchema.parse(numericalToArray(masterlist).map((b) => ({
 			bill_id: b.bill_id,
 			bill_number: b.number,
 			title: b.title,
@@ -789,7 +756,7 @@ var LegiscanClient = class {
 	*/
 	async getBillText({ id }) {
 		const { text } = await this.request("getBillText", { id });
-		return zGetBillText.parse({
+		return BillTextSchema.parse({
 			doc_id: text.doc_id,
 			bill_id: text.bill_id,
 			type: asName(TextType, text.type_id),
@@ -822,7 +789,7 @@ var LegiscanClient = class {
 	async getBill({ id }) {
 		const { bill } = await this.request("getBill", { id });
 		if (!Array.isArray(bill.committee)) bill.committee = [bill.committee];
-		return zGetBill.parse({
+		return BillSchema.parse({
 			bill_id: bill.bill_id,
 			change_hash: bill.change_hash,
 			session_id: bill.session_id,
@@ -1027,7 +994,7 @@ var LegiscanClient = class {
 	*/
 	async getAmendment({ id }) {
 		const { amendment } = await this.request("getAmendment", { id });
-		return zGetAmendment.parse({
+		return AmendmentSchema.parse({
 			amendment_id: amendment.amendment_id,
 			bill_id: amendment.bill_id,
 			adopted: Boolean(amendment.adopted),
@@ -1061,7 +1028,7 @@ var LegiscanClient = class {
 	*/
 	async getSupplement({ id }) {
 		const { supplement } = await this.request("getSupplement", { id });
-		return zGetSupplement.parse({
+		return SupplementSchema.parse({
 			supplement_id: supplement.supplement_id,
 			bill_id: supplement.bill_id,
 			date: supplement.date !== "0000-00-00" ? supplement.date : null,
@@ -1093,7 +1060,7 @@ var LegiscanClient = class {
 	*/
 	async getRollCall({ id }) {
 		const { roll_call } = await this.request("getRollCall", { id });
-		return zGetRollCall.parse({
+		return RollCallSchema.parse({
 			roll_call_id: roll_call.roll_call_id,
 			bill_id: roll_call.bill_id,
 			date: roll_call.date,
@@ -1108,7 +1075,7 @@ var LegiscanClient = class {
 			chamber_raw: roll_call.chamber,
 			votes: numericalToArray(roll_call.votes).map((v) => ({
 				people_id: v.people_id,
-				vote: asName(Vote, v.vote_id),
+				vote: asName(VoteType, v.vote_id),
 				vote_id: v.vote_id,
 				vote_raw: v.vote_text
 			}))
@@ -1121,7 +1088,7 @@ var LegiscanClient = class {
 	*/
 	async getPerson({ id }) {
 		const { person } = await this.request("getPerson", { id });
-		return zGetPerson.parse({
+		return PersonSchema.parse({
 			people_id: person.people_id,
 			person_hash: person.person_hash,
 			party: asName(Party, parseInt(person.party_id, 10)),
@@ -1158,7 +1125,7 @@ var LegiscanClient = class {
 	*/
 	async getSessionPeople({ id }) {
 		const { sessionpeople: { people } } = await this.request("getSessionPeople", { id });
-		return zGetSessionPeople.parse((people ?? []).map((person) => ({
+		return SessionPeopleSchema.parse((people ?? []).map((person) => ({
 			people_id: person.people_id,
 			person_hash: person.person_hash,
 			party: asName(Party, parseInt(person.party_id, 10)),
@@ -1195,7 +1162,7 @@ var LegiscanClient = class {
 	*/
 	async getSponsoredList({ id }) {
 		const { sponsoredbills: { sessions, bills } } = await this.request("getSponsoredList", { id });
-		return zGetSponsoredList.parse(bills.map((b) => ({
+		return SponsoredListSchema.parse(bills.map((b) => ({
 			bill_id: b.bill_id,
 			bill_number: b.number,
 			session: sessions.map((s) => ({
@@ -1245,7 +1212,7 @@ var LegiscanClient = class {
 				...state ? { state: asName(State, state) } : {},
 				...year ? { year: year.toString() } : {}
 			});
-			yield* numericalToArray(searchresult).map((b) => ({
+			yield* SearchSchema.parse(numericalToArray(searchresult).map((b) => ({
 				relevance: b.relevance,
 				state: b.state,
 				state_id: asNumber(State, b.state),
@@ -1258,7 +1225,7 @@ var LegiscanClient = class {
 				last_action: b.last_action,
 				last_action_date: b.last_action_date,
 				title: b.title
-			}));
+			})));
 			page++;
 			if (searchresult.summary.page_total < page) return;
 		}