Skip to content

About

Public TypeScript SDKs for Shirabe

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Shirabe SDKs

Public TypeScript SDKs for Shirabe.

Package Purpose
@shirabe-org/api Typed client generated from Shirabe's OpenAPI contract
@shirabe-org/card Word card renderer and API host adapters

The packages share a repository but remain independent releases. Each has its own manifest, version, tests, npm package, and release tag. The card declares an exact API dependency, so release that API version first.

Development

Use Node 24 or newer.

npm install
npm run check
npx playwright install chromium
npm run test:theme --workspace @shirabe-org/card
npm run test:lookup --workspace @shirabe-org/card
npm run test:review --workspace @shirabe-org/card
npm run test:sign-in --workspace @shirabe-org/card

The SDK owns a watcher-only Parcela environment:

parcela up --detach
parcela logs build
parcela down

It needs a Parcela build that supports services without HTTP. It starts no proxy or playground. Readiness means the watcher process has started; check parcela logs build for initial build success. The setup hook installs dependencies only when node_modules is absent, preserving existing local workspace links.

Build both packages once with npm run build, or run the watcher directly without Parcela:

npm run watch

The watcher builds API before card, including the standalone card bundle. It watches both packages' source and build configuration, rebuilds after edits, and retries on the next edit after a build error. Stop it with Ctrl-C. Run one watcher per SDK checkout. It does not start a web server.

Link consumers separately using Shirabe's bin/sdk link or Reader's npm run sdk:link. Reader's own watcher picks up rebuilt linked packages. Rails keeps a copied card asset, so run npm run sdk:assets in each linked Shirabe web checkout after SDK rebuilds to refresh that copy. The SDK watcher does not write into consumer repositories.

packages/api/openapi/shirabe.bundled.yaml is the reviewed service contract snapshot used for client generation. Update it from a file or URL with:

script/update-openapi [contract]

With no argument, the script fetches the deployed contract from https://shirabe.org/openapi.yaml. It regenerates the client and verifies the API package before returning. A new contract version sets the API manifest to that exact version, updates the card dependency, and increments the card patch version.

Releases

Backend-driven releases

Bump info.version in Shirabe's openapi/shirabe.yaml, regenerate and commit openapi/dist/shirabe.bundled.yaml, and release Shirabe through its production workflow. After production smoke tests and image promotion pass, Shirabe sends backend_release to this repository with the exact production commit SHA.

npm-release.yml fetches that commit's bundled contract, imports it, verifies both packages, and commits the generated SDK and version changes to main. It tags the verified package source, publishes the API first, waits for its npm availability, then publishes the card. It verifies the registry packages and records the GitHub releases. Both packages use the existing npm trusted publishers for npm-release.yml.

Already-published versions are skipped. A retry after partial publication keeps the same versions and finishes the missing package or release record. A same-version contract change or older spec version fails rather than silently publishing an inconsistent SDK. API releases must include a stable, increasing info.version; this workflow does not infer semver from the diff.

To retry a failed dispatch or SDK release, use the SHA from the successful Shirabe production run:

gh workflow run npm-release.yml --repo lostcoords/shirabe-sdk --ref main \
  -f backend_sha=<full-production-commit-sha>

This replaces the daily polling/PR workflow. script/update-openapi remains available for local contract development.

One-time setup

Before enabling the production sender, install this receiver on shirabe-sdk's default branch. Create two fine-grained tokens in GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens, with resource owner lostcoords:

  • Dispatch token: select only shirabe-sdk, grant Contents: read and write, and store it as SDK_REPO_DISPATCH_TOKEN in lostcoords/shirabe.
  • Source token: select only shirabe, grant Contents: read-only, and store it as SHIRABE_SOURCE_TOKEN in lostcoords/shirabe-sdk. Shirabe is private, so the receiver fetches the pinned bundle through the authenticated GitHub Contents API.

Upload each token through the CLI's interactive prompt, not a command-line argument or chat:

gh secret set SDK_REPO_DISPATCH_TOKEN --repo lostcoords/shirabe
gh secret set SHIRABE_SOURCE_TOKEN --repo lostcoords/shirabe-sdk

The ordinary repository GITHUB_TOKEN cannot access another private repository or dispatch across repositories. Complete any organization approval for the tokens and renew them before expiry. gh can upload secrets but cannot create these fine-grained tokens.

The receiver needs Actions to push generated changes and tags. Its job requests contents: write; any branch rules must allow that bot update. Release jobs share one concurrency group so API/card publication and manual releases cannot race. Consumer projects keep their existing pinned dependencies until explicitly updated. Shirabe permits a newer service contract only while it remains compatible with its pinned SDK. Coordinate the consumer migration before deploying breaking API changes.

Independent package releases

For SDK-only changes, bump the selected package version and publish a GitHub release tagged api-v<version> or card-v<version>. The release workflow checks that the tag matches the selected package manifest, verifies both package archives from a clean consumer, and publishes through npm trusted publishing. Publish an API dependency before releasing the card.

With npm 11.19.1, configure both trusted publishers for this repository:

npm trust github @shirabe-org/api --repository lostcoords/shirabe-sdk --file npm-release.yml --allow-publish
npm trust github @shirabe-org/card --repository lostcoords/shirabe-sdk --file npm-release.yml --allow-publish

Enter only npm-release.yml as the workflow filename, not its full path. Verify each configuration with npm trust list <package>. Complete the first successful SDK release before revoking the old Shirabe publisher.

After npm makes both releases available, verify the published archives and a clean registry installation:

bin/package-check --registry

This also verifies npm registry signatures and provenance attestations.

License

The SDKs use the MIT License. This license does not cover the Shirabe service or dictionary data returned by its API.

About

Public TypeScript SDKs for Shirabe

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages