@foir/sdk 0.9.0 → 0.10.0

package/README.md

@@ -29,6 +29,8 @@ pnpm add yjs y-websocket    # for @foir/sdk/realtime
 | `@foir/sdk/react` | Drop-in React auth — `<FoirProvider>` (token or `hostedSession` mode), `useFoirSession`/`useFoirUser`/`useFoirAuth`, `<SignIn>`, `<OAuthButtons>`, `<UserButton>` | `react`, `graphql` |
 | `@foir/sdk/next` | Next.js App Router BFF auth — `createFoirCookieAdapter`, `getFoirSession`, `foirSignIn*`, `completeFoirProviderLogin`, `createFoirMiddleware` | `graphql` |
 | `@foir/sdk/server` | Server-side helpers for extension/config API backends — `createServerClient`, `verifyWebhookSignature`, `verifyScopedToken`, callback client | — |
+| `@foir/sdk/live` | Live reads — the client half of Foir's invalidation graph: tag index, raw-payload store, `seq` ordering, record-change → tag mapping | **none** |
+| `@foir/sdk/live/react` | `<FoirLive>` — one socket, refcounted per model, wired to a query client you already have | `react` |
 | `@foir/sdk/media` | Progressive media — `ProgressiveMedia`, `BlurhashCanvas`, `useProgressiveLoad`, variant-tier adapters | `react` (`hls.js`, `blurhash` optional) |
 | `@foir/sdk/content` | Content-rendering primitives — `createContentRenderer` block dispatch + Lexical `RichTextRenderer` | `react` |
 | `@foir/sdk/realtime` | Thin collaboration helper over `y-websocket` — canonical room addressing, presence, token refresh | `yjs`, `y-websocket` |
@@ -129,6 +131,16 @@ Already have `PLATFORM_API_URL` / `PLATFORM_API_KEY` / `FOIR_PREVIEW` wired for
 the GraphQL path? `createFoirClientFromEnv(env, { generated })` reuses them,
 including the preview `sk_` key and the draft schema channel.
 
+A product built on organizations names the one a request acts in with `orgId`,
+which the client sends as `X-Org-Id` on every request. This is for the PROJECT
+credential — the back-office, or the app that has just resolved a subdomain to
+an organization; a storefront keeps using the credential confined to its own
+organization, which `orgId` cannot steer elsewhere:
+
+```ts
+const foir = createFoirClient({ apiUrl, apiKey, generated, orgId });
+```
+
 ### Typed GraphQL from a server loader
 
 `foirRequest` is a typed `fetch` wrapper, not a GraphQL client: it carries the
@@ -305,6 +317,105 @@ function MyEditor() {
 }
 ```
 
+### Live reads
+
+`@foir/sdk/live` binds a cached read to the server's own dependency graph. Every
+cacheable response already tells you which records and collections it depends
+on, and the change stream already tells you when one of them moved; this is the
+join.
+
+```tsx
+import { FoirLive, useFoirLive, useFoirLiveStatus } from '@foir/sdk/live/react';
+
+<FoirLive
+  queryClient={queryClient}
+  subscribe={(model, options, handlers) => foir[model].onChange({ ...handlers, ...options })}
+>
+  <ProductList />
+</FoirLive>;
+
+function ProductList() {
+  useFoirLive('product');                       // watch, for as long as this is mounted
+  const { newCounts } = useFoirLiveStatus();    // "3 new products — show"
+  // ...
+}
+```
+
+An **adapter**, not a store: you keep the query library you have, and it owns
+your data. What this owns is which entries a change invalidates — matched on the
+record, not the model, so one edit does not refetch every list.
+
+Live is **opt-in per model**. Nothing subscribes because the provider is
+mounted: the shared CDN lane is a major asset, and blanket liveness pushes read
+traffic off it onto the origin.
+
+#### What it is not, and will not become
+
+**No local mutation log, no offline mode, no conflict resolution, no optimistic
+rollback.** The server is authoritative: mutations go over the wire and the
+invalidation comes back.
+
+That is a product boundary rather than a phase. Adding optimistic mutations with
+rollback would make this a different category of library, with its own roadmap
+and a permanent support surface. If you need one, use one — this is not it, and
+its absence is not a bug.
+
+#### Bursts, and the deploy that changes what a response means
+
+A bulk import or a publish sweep fires a burst on one model. `<FoirLive>`
+coalesces it: fifty invalidations of one query inside a 25ms window are one
+refetch, at most four refetches run at once, and a query invalidated again
+mid-refetch is owed exactly one more. Tune with `coalesceWindowMs` and
+`maxConcurrentRefetches`.
+
+Schema drift is separate and easy to miss, because nothing else catches it. A
+deploy that renames a field leaves every cached entry current and quietly wrong
+— no record changed, nothing is out of order, and the bytes describe a schema
+that no longer exists. Wire it up once:
+
+```ts
+import { createFoirDriftHandler } from '@foir/sdk/live';
+
+createFoirClient({
+  // ...
+  onSchemaDrift: createFoirDriftHandler({
+    resync: () => {
+      store.resync();
+      queryClient.clear();
+    },
+  }),
+});
+```
+
+#### Known limitation: mutable sort keys
+
+A query ordered by a mutable key — `updatedAt`, or a `position` a user drags —
+can have a record move between pages when it is updated, so it may appear twice
+or vanish until the next full refetch.
+
+There is deliberately no detection for it: that needs client-side knowledge of
+the sort fields, and the fully correct alternative turns a routine edit into an
+N-page refetch on most feeds. Pass `mode="notify"` on screens where it matters
+and refetch on the user's terms.
+
+#### Pagination, and why the three cases differ
+
+Foir is pure Relay cursor pagination with no `offset`, so loaded pages keep
+their order and `endCursor` stays correct. Only three things break, and each
+gets the treatment the data supports:
+
+- **deleted** — the row is removed by id, with **no fetch**. The event carries
+  the id, so this is instantly correct.
+- **created** — a **count**, not a refetch. A create cannot be spliced (record
+  events carry no body, and you could not place the row without knowing the
+  sort), and refetching the head page prepends under a reader mid-scroll.
+- **updated** — the queries holding that record refetch. Membership is
+  unchanged, so cursors hold.
+
+`totalCount` is flagged approximate rather than adjusted: it is the server's
+count under the query's filter, and guessing would make a stale number into a
+wrong one.
+
 ## License
 
 MIT

package/dist/auth/auth.d.ts

@@ -16,7 +16,7 @@
  */
 import { type FoirEnv } from '../graphql/foir-request';
 import { type AuthOpName, type AuthOpOptions } from './ops';
-import { type AuthConfig, type AuthProviderPublic, type CurrentUser, type CustomerAuthResult, type DefaultAuthProvider, type DeleteAccountResult, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type ProviderToken, type SignupContext, type WaitlistJoinResult } from './operations';
+import { type AuthConfig, type AuthProviderPublic, type CurrentUser, type CustomerAuthResult, type DefaultAuthProvider, type DeleteAccountResult, type MyOrganization, type SelectedOrganization, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type ProviderToken, type SignupContext, type WaitlistJoinResult } from './operations';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 /** An access token + its rotating refresh token. */
 export interface FoirAuthTokens {
@@ -142,6 +142,77 @@ export declare function deleteMyAccount(env: FoirEnv, vars: {
     confirm: boolean;
     password?: string;
 }, options?: AuthOpOptions): Promise<DeleteAccountResult>;
+/**
+ * The organizations this operator may stand in.
+ *
+ * Answered from the CALLING customer's own memberships: each organization they
+ * hold one in and every organization beneath it, so an operator is shown
+ * exactly the set they can stand in, and a customer with no memberships sees
+ * an empty list rather than a refusal. Requires the customer bearer; it is not
+ * the project's inventory and cannot be used as one.
+ */
+export declare function myOrganizations(env: FoirEnv, vars?: {
+    first?: number;
+    after?: string;
+}, options?: AuthOpOptions): Promise<MyOrganization[]>;
+/**
+ * Stand in one of them, for this customer, until they choose otherwise.
+ *
+ * Set once — not per call. The selection is stored against the customer and
+ * resolved into the claim on every subsequent request, so nothing downstream
+ * takes an org argument. Pass an empty `orgId` to clear it and return to the
+ * project-shared view.
+ *
+ * The server authorises the choice against a live membership and refuses
+ * otherwise, so a caller cannot select their way into an organization they do
+ * not run.
+ *
+ * A MEMBERSHIP REACHES DOWNWARD, which is what "a live membership" means now
+ * that organizations nest. Someone who is a member of an organization may stand in any
+ * organization BENEATH it without holding a row of their own there, and
+ * {@link myOrganizations} offers exactly that set — so any id it returned can
+ * be passed here. The reverse never works: a membership at a branch stands in
+ * no ancestor and in no sibling branch, and both are refused as not-found,
+ * which is the same answer an organization that does not exist gets.
+ *
+ * WHAT STANDING THERE MEANS is every membership that reaches the organization
+ * selected. Reach a client through a membership above it and the role shown is
+ * that membership's; authority is the union of every membership that reaches
+ * it, together with the customer's own roles in the project.
+ * {@link MyOrganization.role} names ONE of those roles (the membership held in
+ * the organization itself, when there is one), so it is part of what the next
+ * request resolves and not the whole of it.
+ */
+export declare function selectOrganization(env: FoirEnv, vars: {
+    orgId: string;
+}, options?: AuthOpOptions): Promise<SelectedOrganization>;
+/**
+ * Found an organization, as its first member.
+ *
+ * The caller decides the NAME and, optionally, where it hangs — and nothing
+ * else. The founder is the customer behind the bearer, the id is minted
+ * server-side the way a project's and a tenant's are, and the role they hold in
+ * the new organization is the one the PROJECT named in its settings
+ * (`operatorSignupRole`). The server creates the organization and that one
+ * membership together.
+ *
+ * `parentId` FOUNDS A CHILD, which is what lets your own customer create its own
+ * sub-tenants with no administrator in the loop — a reseller adding a client, a
+ * franchise adding a branch. It is resolved against the caller's own
+ * MEMBERSHIPS, not merely against the project: on this lane "an organization
+ * that exists" is not the question, "one you operate" is, and anything else is
+ * not-found. Omit it to found a root, which is what every registration did
+ * before organizations nested.
+ *
+ * Exists on the wire only while the project's `operatorSignupEnabled` setting
+ * is on; a project that never opted in has no such field, and this refuses
+ * naming it. Returns the same entry `myOrganizations` would then list, role
+ * included, so the application can go straight to {@link selectOrganization}.
+ */
+export declare function registerOrganization(env: FoirEnv, vars: {
+    name: string;
+    parentId?: string;
+}, options?: AuthOpOptions): Promise<MyOrganization>;
 /** Persist an auth result to the session; returns the customer identity. */
 export declare function saveSession(adapter: SessionAdapter, result: CustomerAuthResult): Promise<FoirCustomer>;
 /** Clear all Foir auth keys from the session. */

package/dist/auth/hosted.d.ts

@@ -52,11 +52,78 @@ export interface HostedSession {
     token: string;
     customerId: string;
     email: string;
+    /**
+     * Seconds until `token` lapses, from the endpoint's `expires_in`.
+     *
+     * THIS FLOW HAS NO REFRESH TOKEN — the cookie is the durable credential and
+     * the bearer is re-exchanged when it dies. So a consumer has to know when
+     * that is, and without this the only options are to hardcode the platform's
+     * lifetime (coupling a storefront to a server constant it cannot see) or to
+     * decode `exp` off the JWT. Both re-derive a number the response already
+     * carried, and a consumer that does neither treats a 15-minute bearer as good
+     * forever — which reads as a customer being signed out mid-session.
+     *
+     * Store the death date, not this number: it is seconds from when the exchange
+     * ANSWERED, and a value held across requests is already stale.
+     *
+     * Zero when the endpoint did not report one. Treat that as "expires
+     * imminently" and re-exchange rather than as "never expires".
+     */
+    expiresIn: number;
 }
+/**
+ * The outcome of a hosted-session exchange. The OUTCOME says what to do; the
+ * reason says what happened.
+ *
+ * Collapsing all of this to `null` is what made a transient blip on
+ * `/session/token` indistinguishable from a genuinely signed-out customer. The
+ * only safe-looking action on a bare `null` is to clear the session and send
+ * the customer to the front door, so one 502 signed out a customer whose 30-day
+ * cookie was perfectly valid — and the route's rate limiter is deliberately
+ * fail-open for exactly the opposite reason ("a Redis outage should degrade an
+ * authenticated app, not log it out").
+ */
+export type HostedSessionResult = 
+/** Exchanged. Use `session`. */
+{
+    outcome: 'active';
+    session: HostedSession;
+}
+/**
+ * The customer is signed out. Act on it: clear any local session and send
+ * them to `hostedLoginUrl`.
+ *
+ * `no-cookie` — nothing to exchange. `rejected` — the front door refused the
+ * cookie (401) and has already cleared it itself.
+ */
+ | {
+    outcome: 'signed-out';
+    reason: 'no-cookie' | 'rejected';
+}
+/**
+ * The exchange could not be completed, and it says NOTHING about whether the
+ * customer is signed in. KEEP the existing session, serve the request, try
+ * again on the next one.
+ *
+ * `forbidden` is the odd one: a 403 means the CSRF header did not arrive
+ * (a proxy stripping it, most likely), which is a misconfiguration rather
+ * than a blip. Retrying will not fix it — but signing the customer out would
+ * be wrong, so the safe action is the same and it is grouped by that.
+ */
+ | {
+    outcome: 'unavailable';
+    reason: 'forbidden' | 'server-error' | 'rate-limited' | 'network' | 'malformed';
+    /** Present when a response arrived at all. */
+    httpStatus?: number;
+    /** The thrown value, for `network`. */
+    cause?: unknown;
+};
 /**
  * Exchange the hosted-login cookie on an incoming request for a customer
- * bearer + identity (server-to-server: forwards the cookie to the front
- * door's session endpoint with the CSRF header). Returns null when there's no
- * cookie or it's expired/revoked.
+ * bearer + identity (server-to-server: forwards the cookie to the front door's
+ * session endpoint with the CSRF header).
+ *
+ * See `HostedSessionResult` for why this reports an outcome rather than
+ * returning `null` for everything that is not a success.
  */
-export declare function fetchHostedSession(request: Request, config: HostedLoginConfig): Promise<HostedSession | null>;
+export declare function fetchHostedSession(request: Request, config: HostedLoginConfig): Promise<HostedSessionResult>;

package/dist/auth/index.d.ts

@@ -10,12 +10,12 @@
  * the caller's own manifest advertises, through the same op transport
  * `@foir/sdk/data` uses, so `graphql` is not on this module's path at all.
  */
-export { customerLogin, customerRegister, customerRequestOTP, customerLoginOTP, customerRefreshToken, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, getAuthProviders, getAuthConfig, getDefaultAuthProvider, customerSignupContext, customerJoinWaitlist, customerRequestPasswordReset, customerResetPassword, customerUpdatePassword, customerVerifyEmail, currentUser, myProviderToken, customerLogout, deleteMyAccount, saveSession, clearSession, getSessionToken, getSessionCustomer, loginWithPassword, registerWithPassword, loginWithOTP, resetPasswordAndSignIn, refreshSession, signOut, authedRequest, authedOp, requireAuth, requireAdmin, } from './auth';
+export { customerLogin, customerRegister, customerRequestOTP, customerLoginOTP, customerRefreshToken, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, getAuthProviders, getAuthConfig, getDefaultAuthProvider, customerSignupContext, customerJoinWaitlist, customerRequestPasswordReset, customerResetPassword, customerUpdatePassword, customerVerifyEmail, currentUser, myProviderToken, customerLogout, deleteMyAccount, myOrganizations, selectOrganization, registerOrganization, saveSession, clearSession, getSessionToken, getSessionCustomer, loginWithPassword, registerWithPassword, loginWithOTP, resetPasswordAndSignIn, refreshSession, signOut, authedRequest, authedOp, requireAuth, requireAdmin, } from './auth';
 export type { FoirAuthTokens, FoirCustomer, FoirUser, SessionAdapter, RequireAuthOptions, RequireAdminOptions, } from './auth';
 export { AUTH_OPS } from './ops';
 export type { AuthOpName, AuthOpOptions } from './ops';
 export { hostedLoginUrl, hostedLogoutUrl, fetchHostedSession } from './hosted';
-export type { HostedLoginConfig, HostedSession } from './hosted';
+export type { HostedLoginConfig, HostedSession, HostedSessionResult } from './hosted';
 export { createFoirSessionClient } from './session-client';
 export type { FoirSessionClient, FoirSessionConfig, FoirSessionUser, } from './session-client';
-export type { CustomerAuthResult, ProviderLoginResult, AuthProviderPublic, ProviderLoginInput, ProviderCallbackInput, ProviderOTPVerifyInput, SignupContext, SignupMode, WaitlistJoinResult, AuthConfig, AuthConfigProvider, DefaultAuthProvider, CurrentUser, ProviderToken, DeleteAccountResult, } from './operations';
+export type { CustomerAuthResult, ProviderLoginResult, AuthProviderPublic, ProviderLoginInput, ProviderCallbackInput, ProviderOTPVerifyInput, SignupContext, SignupMode, WaitlistJoinResult, AuthConfig, AuthConfigProvider, DefaultAuthProvider, CurrentUser, ProviderToken, DeleteAccountResult, MyOrganization, SelectedOrganization, } from './operations';

package/dist/auth/operations.d.ts

@@ -142,3 +142,87 @@ export interface DeleteAccountResult {
     recordsDeleted: number;
     filesDeleted: number;
 }
+/**
+ * One organization the calling operator may stand in, as `myOrganizations`
+ * returns it.
+ *
+ * Identity, not configuration: the id to hand to {@link selectOrganization}, a
+ * name to render, the status, and where it sits. Only active organizations are
+ * returned today; `status` is here so that a widening is visible to the caller
+ * rather than silent.
+ *
+ * There is no `key`. An organization is identified by a server-minted id, the
+ * way a project and a tenant are; the subdomain a SaaS addresses its own
+ * tenants by is a record the SaaS models and reads for itself, and it was never
+ * this surface's to hand out.
+ *
+ * THE LIST IS A SUBTREE. A membership at an organization reaches everything
+ * beneath it, so an operator who runs a group is offered the group and every
+ * client under it. Draw it flat and a reseller's clients render as its
+ * siblings, which is what the three position fields are for.
+ */
+export interface MyOrganization {
+    id: string;
+    name: string;
+    status: string;
+    /**
+     * The immediate parent, or null for a root.
+     *
+     * A root OF THE PROJECT, not of the caller's view: an operator whose
+     * membership sits three levels down sees their own organization with a parent
+     * they cannot read. Null means there is no parent; it is never the empty
+     * string, because that is a third value with no reading.
+     */
+    parentId: string | null;
+    /**
+     * Every ancestor, ROOT FIRST, ending at the immediate parent. Empty for a
+     * project root.
+     *
+     * IDS, not names, and the whole path — including ancestors this caller cannot
+     * read. An id is disclosed to everything below it; a name is row content an
+     * operator further down may not be entitled to. A path trimmed to the
+     * readable ancestors would have gaps or a false root, and two operators of
+     * one organization would then see different paths to it.
+     */
+    ancestorIds: string[];
+    /**
+     * Levels above this organization in the PROJECT's tree: 0 is a project root.
+     *
+     * The project's depth rather than the caller's, so two operators looking at
+     * the same organization agree about where it is. Indent by the difference
+     * from the shallowest entry in the list if you want the caller's own view.
+     */
+    depth: number;
+    /**
+     * The caller's own role in this organization, or null when their
+     * membership carries none (or a disabled one). Never another member's role.
+     *
+     * ONE ROLE, NOT THE WHOLE AUTHORITY. The platform resolves the operator's
+     * authority per request as the union of the roles on every membership that
+     * reaches this organization (one held in it and every one held above it),
+     * together with their own roles in the project. This field is the role of
+     * the membership held in the organization itself when there is one, and
+     * otherwise the role of a membership above it, so an application reading it
+     * sees part of what the next request is allowed and not the whole of it.
+     */
+    role: MyOrganizationRole | null;
+}
+/** A role as `myOrganizations` reports it: enough to match a policy and to render. */
+export interface MyOrganizationRole {
+    id: string;
+    key: string;
+    name: string;
+    permissions: string[];
+}
+/**
+ * Where the caller now stands, as `selectMyOrganization` returns it.
+ *
+ * Two fields, because two are all there is to say. It is NOT a session context:
+ * an operator is a customer, and the platform's admin session shape — user,
+ * available tenants, effective permissions — describes a population this level
+ * exists to keep them out of.
+ */
+export interface SelectedOrganization {
+    orgId: string;
+    orgName: string;
+}

package/dist/auth/ops.d.ts

@@ -56,6 +56,9 @@ export declare const AUTH_OPS: {
     readonly customerUpdatePassword: "customerUpdatePassword";
     readonly customerVerifyEmail: "customerVerifyEmail";
     readonly deleteMyAccount: "deleteMyAccount";
+    readonly myOrganizations: "myOrganizations";
+    readonly selectMyOrganization: "selectMyOrganization";
+    readonly registerOperatorOrganization: "registerOperatorOrganization";
     readonly customerLoginWithProvider: "customerLoginWithProvider";
     readonly customerProviderCallback: "customerProviderCallback";
     readonly customerProviderVerifyOTP: "customerProviderVerifyOTP";
@@ -71,6 +74,13 @@ export interface AuthOpOptions {
      * authorised by. Ignored by the pre-credential ops, which mint it.
      */
     bearerToken?: string;
+    /**
+     * The organization the call acts in, sent as `X-Org-Id` — same contract as
+     * `FoirClientConfig.orgId`, because these ops ride the same transport. For a
+     * project credential acting inside one of its organizations; a credential
+     * already confined to an organization may only name its own.
+     */
+    orgId?: string;
     /**
      * `fetch` implementation. Defaults to `globalThis.fetch`. Injectable for
      * tests and for runtimes that hand you a bound `fetch` (Hydrogen/Oxygen).