@flow-industries/id 0.22.0 → 0.23.0

package/README.md

@@ -37,15 +37,24 @@ bun add @flow-industries/id wagmi viem @tanstack/react-query
 
 ## Documentation
 
-Full documentation at **[docs.flow.industries/en/auth](https://docs.flow.industries/en/auth)**.
+- [Integration guide](docs/integration-guide.md) — server setup, canonical sign-in, React, and account navigation.
+- [Guest sessions](docs/guest-sessions.md) — silent guest creation and preserving identity during signup.
+- [Action sessions](docs/action-sessions.md) — activity timing and the inline action widget.
 
-- [Getting started](https://docs.flow.industries/en/auth/getting-started) - install the SDK and ship a login button
-- [Concepts](https://docs.flow.industries/en/auth/concepts) - passkeys, audience-bound JWTs, sessions, and access keys
-- [SDK](https://docs.flow.industries/en/auth/sdk/create-flow) - `createFlow`, React hooks, Wagmi connector, and direct dialog control
-- [Wagmi](https://docs.flow.industries/en/auth/sdk/wagmi) - use Flow ID as a Wagmi connector
-- [Signing](https://docs.flow.industries/en/auth/signing) - messages, typed data, transactions, and batch calls
-- [JWT verify](https://docs.flow.industries/en/auth/jwt-verify) - verify Flow sessions on your backend
-- [API reference](https://docs.flow.industries/en/auth/api) and [self-hosting](https://docs.flow.industries/en/auth/self-hosting)
+The Auth pages in the separate documentation repository are archived. Use the
+guides here for the current SDK integration.
+
+## Sign-in and account pages
+
+The SDK starts sign-in through your app's first-party `/flow/session` handler
+and navigates to Flow ID's `/authorize` page. Completion returns to the saved
+app path; read the new session after navigation instead of continuing after
+`await flow.login()`.
+
+`ProfileButton` and `flow.openAccount()` open `/account` in a normal new tab.
+The source app stays loaded and refreshes its session on refocus. Sign-in and
+own-account management no longer use an embedded dialog. See the
+[integration guide](docs/integration-guide.md) for server wiring and migration.
 
 ## Public profile overlays
 
@@ -82,3 +91,55 @@ pointer lock before opening, then use `onClose` to restore their input state.
 ## License
 
 MIT
+
+
+### Migration compatibility checks
+
+`bun run db:check` regenerates into a temporary directory and refuses schema drift or edits
+to previously committed SQL. CI compares against the PR base or previous main commit.
+`bun run test:migrations` exercises the committed chain, the supported previous schema,
+current projections, older writes after upgrade, and deliberate missing-migration failures.
+`MIGRATION_TEST_DATABASE_URL=postgres://... bun scripts/postgres-acceptance.ts` additionally
+creates a unique disposable database on a test PostgreSQL server, runs the real migration
+entrypoint, rejects a changed applied hash, and proves a failing final migration rolls back
+both its schema changes and ledger entry. The test deletes only its own generated database.
+
+The initial compatibility baseline is source `1bda372b69e2f66a3dc0cbb244bcbe7cb858f493` (schema through `0035`).
+The tests freeze representative older SQL reads/writes; they do not boot every historical
+application version. Advance this baseline deliberately when retiring support, and extend
+the fixtures when changing a persisted contract. Migration failures block the image build;
+production's PreSync job also refuses an applied ledger that is not an exact committed prefix.
+
+Application rollback keeps the expanded schema. Pin the latest verified migration image via
+Mesh's `migrate.image` while restoring the previous compatible application image. Do not run
+down migrations or point an older migration image at a newer ledger: that is refused. A
+destructive contract migration needs an explicit support-boundary change after older writers
+and browser clients have drained.
+
+## Versioned consumer contracts
+
+`bun run contracts:generate` produces the published
+`@flow-industries/id/contracts/v1/reports.json` and `openapi.json` artifacts from
+the same schemas used by the XP, action, presence and position handlers.
+`bun run contracts:check` rejects stale output and incompatible changes to the
+existing v1 request schema against `CONTRACT_BASE_REF` (default `origin/main`).
+Keep existing v1 fields compatible; a breaking boundary needs a new version and
+an overlap plan for deployed consumers.
+
+Trusted service consumers can call `createReportsApi(host, serviceToken)` from
+`@flow-industries/id`. The returned function accepts the operation name and its
+typed request, validates both the outgoing request and successful response, and
+throws `ReportRequestError` for non-success responses. Use the XP reporting
+credential for action/XP operations and the room credential for presence/position;
+never ship either service credential to a browser.
+
+`bun run test:sdk-package` builds, packs and installs the actual SDK artifact in
+a disposable consumer, checks public imports and declarations, and proves a
+removed contract export fails. Producer tests execute the typed client against
+real report handlers and validate minted guest/full session and JWT shapes.
+CI gates both container and package publication on these checks.
+
+The current OpenAPI artifact describes the service report boundary. The remaining
+account, room management, study, settings, session and passkey HTTP operations
+still need complete request/response descriptions and generated client coverage
+before the full HTTP contract work is complete.