docs: add the @hypercerts-org/api package (Hypercerts API types)

docs-sources.yml

@@ -14,6 +14,14 @@ sources:
     trackRelease: true
     releaseTagPrefix: '@hypercerts-org/happyview-modules@'
 
+  - id: api-types-changelog
+    title: Hypercerts API types changelog
+    repo: hypercerts-org/api
+    ref: main
+    path: packages/api/CHANGELOG.md
+    trackRelease: true
+    releaseTagPrefix: '@hypercerts-org/api@'
+
   - id: cgs-changelog
     title: Certified Group Service changelog
     repo: hypercerts-org/certified-group-service

docs/remote-markdown.md

@@ -109,7 +109,7 @@ External Markdown is parsed with the same Markdoc configuration as local pages.
 
 `lib/protocol-releases.json` holds the reviewed, human-readable protocol major/minor history, newest first. The Lexicon package's major/minor version defines the protocol line; each entry records the matching Lexicon release version and publication date. Review the generated Lexicon changelog in its release PR before publication and write the protocol note in Docs as part of the same release process. Explain the purpose, changes, and compatibility without duplicating every technical entry. A Lexicon patch updates the component changelog and badge, but does not need another protocol entry. `cardSummary` is the short explanation on the Releases overview. An optional `blogUrl` adds a release-article link when an article is actually published.
 
-`lib/release-components.json` names the seven participating components and their local changelog routes. A `sourceId` connects a component to a release-tracked source in `docs-sources.yml`. Components without a published release display **Under development**; the new SDK has no source repository attached yet. Entryway is separate from the preceding ePDS product, and HappyView's version is not substituted for the Hypercerts API version.
+`lib/release-components.json` names the eight participating components and their local changelog routes. A `sourceId` connects a component to a release-tracked source in `docs-sources.yml`. Components without a published release display **Under development**; the new SDK has no source repository attached yet. Entryway is separate from the preceding ePDS product, and HappyView's version is not substituted for the Hypercerts API version.
 
 During generation, `lib/release-catalog.json` holds the compact version/status data used by the sidebar. The same catalog is saved inside the external content snapshot. Local pages use these standalone build-time markers:
 

lib/release-components.json

@@ -14,6 +14,13 @@
     "sourceId": "api-changelog",
     "unreleasedLabel": "Production (unreleased)"
   },
+  {
+    "id": "api-types",
+    "title": "Hypercerts API types",
+    "path": "/releases/api-types",
+    "description": "The @hypercerts-org/api npm package: typed query definitions for calling the Hypercerts API with @atproto/lex.",
+    "sourceId": "api-types-changelog"
+  },
   {
     "id": "sdk",
     "title": "Hypercerts SDK",

pages/reference/sdk.md

@@ -16,5 +16,6 @@ Once released, this section will cover the SDK's exports and types, validation a
 Until then:
 
 - The [`@hypercerts-org/lexicon`](https://www.npmjs.com/package/@hypercerts-org/lexicon) package provides the schemas, TypeScript types, and record validation. [Introduction to Lexicons](/lexicons/introduction-to-lexicons) shows how to validate a record before writing it.
+- The [`@hypercerts-org/api`](https://www.npmjs.com/package/@hypercerts-org/api) package provides typed queries for the Hypercerts API. [API and indexer](/reference/services/hypercerts-api#from-typescript) shows how to call it.
 - [Client Integration](/client-integration) describes what is available for building today.
 - Follow the SDK's status on [Releases](/releases/sdk).

pages/reference/services/hypercerts-api.md

@@ -23,7 +23,7 @@ The API returns indexed views rather than bare records. Depending on the method,
 
 ## Using it from your application
 
-XRPC names each HTTP method with an NSID (Namespaced Identifier) at `/xrpc/<NSID>`. Queries use `GET` with URL parameters. The public read queries need no user session. Call them directly or use the [SDK](/reference/sdk) when available.
+XRPC names each HTTP method with an NSID (Namespaced Identifier) at `/xrpc/<NSID>`. Queries use `GET` with URL parameters. The public read queries need no user session. Call them directly, or from TypeScript with the `@hypercerts-org/api` package below.
 
 For example, retrieve an activity by its full AT-URI. Replace the placeholders with the DID and record key of an activity available to the API:
 
@@ -33,6 +33,28 @@ curl --get 'https://api.hypercerts.dev/xrpc/org.hypercerts.claim.getActivity' \
   --data-urlencode "uri=$activity_uri"
 ```
 
+### From TypeScript
+
+[`@hypercerts-org/api`](https://www.npmjs.com/package/@hypercerts-org/api) provides typed definitions of every query for the [`@atproto/lex`](https://www.npmjs.com/package/@atproto/lex) client. Each query sits at its NSID path, with typed parameters and response views; the records inside the views have the types from [`@hypercerts-org/lexicon`](/lexicons/introduction-to-lexicons).
+
+```bash
+pnpm add @hypercerts-org/api @hypercerts-org/lexicon @atproto/lex
+```
+
+```typescript
+import { Client } from "@atproto/lex";
+import { org } from "@hypercerts-org/api";
+
+const api = new Client("https://api.hypercerts.dev", { validateResponse: false });
+
+const { activity } = await api.call(org.hypercerts.claim.getActivity, {
+  uri: "at://<author-did>/org.hypercerts.claim.activity/<record-key>",
+});
+console.log(activity.record.title);
+```
+
+`Client` validates responses against the lexicons by default. The API can still return some records that fail their lexicon, and one such record fails a whole list response, so turn response validation off for now (`validateResponse: false`) and read fields defensively. See the [package README](https://github.com/hypercerts-org/api/tree/main/packages/api#response-validation). The package's versions are listed under [Hypercerts API types releases](/releases/api-types).
+
 The API is for indexed reads, not repository writes. New or updated records may take time to appear.
 
 Choose another read path when it better fits your use case:
@@ -43,4 +65,4 @@ Choose another read path when it better fits your use case:
 
 ## Status and source
 
-Production endpoint: [`api.hypercerts.dev`](https://api.hypercerts.dev). See [Hypercerts API releases](/releases/api) for its changelog and the [API repository](https://github.com/hypercerts-org/api) for source code.
+Production endpoint: [`api.hypercerts.dev`](https://api.hypercerts.dev). See [Hypercerts API releases](/releases/api) for the service's changelog, [Hypercerts API types releases](/releases/api-types) for the `@hypercerts-org/api` package, and the [API repository](https://github.com/hypercerts-org/api) for source code.

pages/releases/api-types.md

@@ -0,0 +1,6 @@
+---
+title: Hypercerts API Types Releases
+description: Release history of @hypercerts-org/api, the TypeScript query definitions for the Hypercerts API, imported from the API repository.
+externalDoc: api-types-changelog
+repositoryLink: true
+---

test/external-docs.test.js

@@ -218,6 +218,22 @@ test('configures API releases from the package changelog and scoped tag', () =>
   });
 });
 
+test('configures the API types package releases from its own changelog and scoped tag', () => {
+  const source = loadExternalDocSources().find(({ id }) => id === 'api-types-changelog');
+  assert.deepEqual(source, {
+    id: 'api-types-changelog',
+    title: 'Hypercerts API types changelog',
+    repo: 'hypercerts-org/api',
+    ref: 'main',
+    path: 'packages/api/CHANGELOG.md',
+    trackRelease: true,
+    releaseTagPrefix: '@hypercerts-org/api@',
+  });
+
+  const page = readFileSync(join(__dirname, '..', 'pages', 'releases', 'api-types.md'), 'utf8');
+  assert.equal(parseMarkdownFrontmatter(page).externalDoc, 'api-types-changelog');
+});
+
 test('release page links to its source repository in rendering and raw Markdown', () => {
   const localMarkdown = '---\nexternalDoc: epds\nrepositoryLink: true\n---\n';
   const frontmatter = parseMarkdownFrontmatter(localMarkdown);