client: add @hypercerts-org/api with record types from @hypercerts-org/lexicon/records

.agents/skills/writing-changesets/SKILL.md

@@ -17,11 +17,11 @@ Do not add one for documentation-only or test-only changes, changes to the separ
 
 ## Package and version bump
 
-The bundle is versioned as one unit. The Changeset frontmatter must target only `@hypercerts-org/hypercerts-api`:
+The bundle is versioned as one unit. The Changeset frontmatter must target only `@hypercerts-org/happyview-modules`:
 
 ```md
 ---
-'@hypercerts-org/hypercerts-api': patch
+'@hypercerts-org/happyview-modules': patch
 ---
 
 A short, clear summary of the change.
@@ -58,18 +58,18 @@ Use bullets only when there are several distinct actions or changes to scan. Omi
 
 ## Procedure
 
-1. Check the actual diff and read `.changeset/README.md` plus `api/README.md` for the current scope and release behavior.
-2. Run `pnpm changeset` and select `@hypercerts-org/hypercerts-api`, or create a descriptive Markdown file under `.changeset/` with the required frontmatter.
+1. Check the actual diff and read `.changeset/README.md` plus `happyview-modules/README.md` for the current scope and release behavior.
+2. Run `pnpm changeset` and select `@hypercerts-org/happyview-modules`, or create a descriptive Markdown file under `.changeset/` with the required frontmatter.
 3. Write and review the summary using the plain-language guidance above. Make any adaptation steps concrete and accurate.
 4. Run `pnpm changeset status` to check that the Changeset is valid and targets the intended package.
 
 ## Release context
 
-`@hypercerts-org/hypercerts-api` is marked `"private": true` in `api/package.json`, which prevents it from being published to npm. This flag applies to the package, not the public GitHub repository. Changesets creates a release pull request that updates `api/package.json` and `api/CHANGELOG.md`. After that pull request is merged, CI validates the merged commit and creates a version tag and public GitHub Release. Operators install from the tagged source; this process does not deploy the bundle to a HappyView instance.
+`@hypercerts-org/happyview-modules` is marked `"private": true` in `happyview-modules/package.json`, which prevents it from being published to npm. This flag applies to the package, not the public GitHub repository. Changesets creates a release pull request that updates `happyview-modules/package.json` and `happyview-modules/CHANGELOG.md`. After that pull request is merged, CI validates the merged commit and creates a version tag and public GitHub Release. Operators install from the tagged source; this process does not deploy the bundle to a HappyView instance.
 
 ## Repository references
 
 - `.changeset/README.md` — package scope, bump rules, and release process.
 - `.changeset/config.json` — Changesets configuration and ignored packages.
-- `api/package.json` — package name and version.
-- `api/README.md` — bundle installation and distribution details.
+- `happyview-modules/package.json` — package name and version.
+- `happyview-modules/README.md` — bundle installation and distribution details.

.changeset/README.md

@@ -6,8 +6,8 @@ Add a Changeset when a pull request changes the installable API bundle or its op
 pnpm changeset
 ```
 
-Target `@hypercerts-org/hypercerts-api` and write release notes for endpoint or schema additions, compatible behavior changes, fixes, breaking changes, and installer or configuration changes that operators need to know about. Use `patch` for compatible fixes, `minor` for additive API capabilities, and `major` for incompatible API changes.
+Target `@hypercerts-org/happyview-modules` and write release notes for endpoint or schema additions, compatible behavior changes, fixes, breaking changes, and installer or configuration changes that operators need to know about. Use `patch` for compatible fixes, `minor` for additive API capabilities, and `major` for incompatible API changes.
 
 The API bundle is versioned as one unit. Do not add Changesets for the separate endpoint-explorer package, documentation-only changes, tests, or release/CI maintenance that does not change the installable bundle. If the release impact is unclear, decide with the reviewer rather than guessing a version bump.
 
-A Changesets release PR updates `api/package.json` and `api/CHANGELOG.md`. After it is merged to `main`, release CI validates that exact commit and creates an `@hypercerts-org/hypercerts-api@X.Y.Z` Git tag and public GitHub Release. The bundle is not published to npm; operators retrieve the tagged source from this public repository and install it into their own HappyView instance.
+A Changesets release PR updates `happyview-modules/package.json` and `happyview-modules/CHANGELOG.md`. After it is merged to `main`, release CI validates that exact commit and creates an `@hypercerts-org/happyview-modules@X.Y.Z` Git tag and public GitHub Release. The bundle is not published to npm; operators retrieve the tagged source from this public repository and install it into their own HappyView instance.

.changeset/actor-reactions-batch-lookup.md

@@ -1,5 +1,5 @@
 ---
-'@hypercerts-org/hypercerts-api': minor
+'@hypercerts-org/happyview-modules': minor
 ---
 
 Add `app.certified.feed.getActorReactions` to return an actor's indexed likes and reposts for up to 100 subject records in one request, preserving request order and duplicates.

.changeset/batch-follow-queries.md

@@ -1,5 +1,5 @@
 ---
-'@hypercerts-org/hypercerts-api': minor
+'@hypercerts-org/happyview-modules': minor
 ---
 
 Clients can check multiple actor or entity follow relationships in one request. The new batch queries return one explicitly keyed result for each supplied target, preserving request order and duplicates; null means no indexed relationship, while lookup failures remain errors.

.changeset/batch-reaction-counts.md

@@ -1,5 +1,5 @@
 ---
-'@hypercerts-org/hypercerts-api': minor
+'@hypercerts-org/happyview-modules': minor
 ---
 
 Add a public query that returns like and repost counts for up to 100 subject records at a time.

.changeset/config.json

@@ -12,7 +12,7 @@
   "access": "restricted",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": ["hypercerts-api-endpoints"],
+  "ignore": ["hypercerts-api-endpoints", "@hypercerts-org/api"],
   "privatePackages": {
     "version": true,
     "tag": true

.changeset/entity-follower-total-count.md

@@ -1,5 +1,5 @@
 ---
-'@hypercerts-org/hypercerts-api': minor
+'@hypercerts-org/happyview-modules': minor
 ---
 
 Entity follower results now include `totalCount`, the number of distinct actor–entity relationships before pagination. The count is also returned when a page has no followers.

.changeset/rename-happyview-modules.md

@@ -0,0 +1,5 @@
+---
+'@hypercerts-org/happyview-modules': patch
+---
+
+Rename the package from `@hypercerts-org/hypercerts-api` to `@hypercerts-org/happyview-modules`, and its directory from `api/` to `happyview-modules/`, so the name says what it is and `@hypercerts-org/api` is free for the TypeScript package. Release tags from this release on are `@hypercerts-org/happyview-modules@X.Y.Z`; earlier releases keep their `@hypercerts-org/hypercerts-api@X.Y.Z` tags. The installer is run from `happyview-modules/` instead of `api/`; the modules themselves are unchanged.

.github/workflows/hypercerts-api.yml

@@ -14,6 +14,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   checks:
     name: API validation and build
@@ -38,13 +42,12 @@ jobs:
       - name: Install Luacheck
         run: luarocks install luacheck 1.2.0
 
+      # Reads the pnpm version from the packageManager field in package.json.
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
-        with:
-          version: 10.15.1
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: 24
+          node-version-file: .nvmrc
           cache: pnpm
           cache-dependency-path: pnpm-lock.yaml
 
@@ -69,6 +72,9 @@ jobs:
       - name: Build API Lua bundles and explorer
         run: pnpm build
 
+      - name: Check the packed @hypercerts-org/api in a clean consumer
+        run: pnpm --filter @hypercerts-org/api run check:package
+
   runtime-contracts:
     name: HTTP tests (HappyView + PostgreSQL)
     runs-on: ubuntu-latest
@@ -90,13 +96,12 @@ jobs:
           ln -s "$lua_bin" "${lua_bin%/*}/lua5.4"
           lua5.4 -e 'assert(_VERSION == "Lua 5.4", "expected Lua 5.4")'
 
+      # Reads the pnpm version from the packageManager field in package.json.
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
-        with:
-          version: 10.15.1
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: 24
+          node-version-file: .nvmrc
           cache: pnpm
           cache-dependency-path: pnpm-lock.yaml
 
@@ -154,8 +159,8 @@ jobs:
             "$runner_temp"/hypercerts-http-*/compose.env) ;;
             *) echo "Refusing cleanup for credentials outside RUNNER_TEMP: $env_file" >&2; exit 1 ;;
           esac
-          compose_file="$(realpath "$GITHUB_WORKSPACE/api/docker-compose.contracts.yml")"
-          compose=(docker compose --project-name "$project" --env-file "$env_file" --project-directory "$GITHUB_WORKSPACE/api" -f "$compose_file")
+          compose_file="$(realpath "$GITHUB_WORKSPACE/happyview-modules/docker-compose.contracts.yml")"
+          compose=(docker compose --project-name "$project" --env-file "$env_file" --project-directory "$GITHUB_WORKSPACE/happyview-modules" -f "$compose_file")
           container_ids="$("${compose[@]}" ps --all --quiet)"
           while IFS= read -r id; do
             [[ -n "$id" ]] || continue

.github/workflows/release.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: 24
+          node-version-file: .nvmrc
           cache: pnpm
           cache-dependency-path: pnpm-lock.yaml
 
@@ -73,7 +73,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: 24
+          node-version-file: .nvmrc
           cache: pnpm
           cache-dependency-path: pnpm-lock.yaml
 
@@ -146,7 +146,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: 24
+          node-version-file: .nvmrc
           cache: pnpm
           cache-dependency-path: pnpm-lock.yaml
 
@@ -167,10 +167,10 @@ jobs:
           GITHUB_REPOSITORY: ${{ github.repository }}
         run: |
           set -euo pipefail
-          package_name="$(node --print "require('./api/package.json').name")"
-          version="$(node --print "require('./api/package.json').version")"
+          package_name="$(node --print "require('./happyview-modules/package.json').name")"
+          version="$(node --print "require('./happyview-modules/package.json').version")"
           if [ -z "$package_name" ] || [ -z "$version" ]; then
-            echo "::error::Could not derive the API bundle name and version from api/package.json"
+            echo "::error::Could not derive the API bundle name and version from happyview-modules/package.json"
             exit 1
           fi
           tag="${package_name}@${version}"

.nvmrc

@@ -0,0 +1 @@
+24

AGENTS.md

@@ -1,8 +1,9 @@
 # Agent instructions
 
 - Use the repository-pinned pnpm version and preserve the lockfile.
-- Treat `api/manifest.json` as authoritative for the API modules included in this checkout.
-- For API endpoint, contract, or externally visible query-behavior changes, review the user-facing docs and update `.agents/skills/hypercerts-api/` in the same change. This includes the endpoint explorer in `docs/`; keep its committed Lexicon/OpenAPI snapshots and coverage metadata aligned with `api/manifest.json`, module manifests, and handler behavior, and update explorer tests when relevant. Keep the skill's bundled OpenAPI snapshot, endpoint map, and relevant consumer guidance aligned too; because the skill is distributed without this repository, keep its references self-contained and free of repo-relative contract links.
+- Treat `happyview-modules/manifest.json` as authoritative for the API modules included in this checkout.
+- For API endpoint, contract, or externally visible query-behavior changes, review the user-facing docs and update `.agents/skills/hypercerts-api/` in the same change. This includes the endpoint explorer in `docs/`; keep its committed Lexicon/OpenAPI snapshots and coverage metadata aligned with `happyview-modules/manifest.json`, module manifests, and handler behavior, and update explorer tests when relevant. Keep the skill's bundled OpenAPI snapshot, endpoint map, and relevant consumer guidance aligned too; because the skill is distributed without this repository, keep its references self-contained and free of repo-relative contract links.
+- When a query Lexicon, `happyview-modules/manifest.json`, the `@hypercerts-org/lexicon` version in `packages/api/package.json` or the `@atproto/lex` version changes, run `pnpm client:generate` and commit the regenerated `packages/api/src/`. Do not edit generated files there by hand.
 - Read [CONTRIBUTING.md](CONTRIBUTING.md) for local validation and HTTP runtime test requirements before changing test or installer behavior.
 - `pnpm install:api` sends admin requests to a HappyView instance and uploads assets. Do not run it unless the user explicitly approves the target and token in the current conversation.
 - HTTP runtime tests use a task-owned local Compose project and disposable database. Do not target or tear down unrelated services; note that the Compose bridge network permits egress and the configured proxy is not network-level isolation.