@flow-industries/id 0.10.0 → 0.12.0

package/dist/sdk/start/index.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * TanStack Start integration — the whole Flow ID wiring a Start app needs,
+ * so integrating a new domain is one route file plus one root wrapper:
+ *
+ * ```tsx
+ * // src/routes/flow.session.ts — the first-party session route + SSR fn
+ * import { createServerFn } from "@tanstack/react-start";
+ * import { createFileRoute } from "@tanstack/react-router";
+ * import { flowSessionHandlers, resolveFlowSessionRequest } from "@flow-industries/id/start/server";
+ *
+ * export const getFlowSession = createServerFn({ method: "GET" }).handler(resolveFlowSessionRequest);
+ * export const Route = createFileRoute("/flow/session")({ server: { handlers: flowSessionHandlers() } });
+ *
+ * // src/routes/__root.tsx
+ * beforeLoad: () => flowSessionContext(getFlowSession),
+ * // and in the root component:
+ * <FlowRoot session={session}>{children}</FlowRoot>
+ * ```
+ *
+ * The server fn stays in app source because TanStack's compiler splits it
+ * into the server bundle there; everything it does lives here.
+ */
+import { useMemo } from "react";
+import { createFlow, createStaticFlow, getFlow } from "../client";
+import { FlowIdProvider } from "../react";
+/**
+ * The `beforeLoad` body: during SSR resolve the session server-side (via the
+ * app's `getFlowSession` server fn, which appends rotated Set-Cookie values);
+ * in the browser snapshot the live singleton instead — no network.
+ */
+export async function flowSessionContext(getSession) {
+    if (typeof window === "undefined")
+        return { session: await getSession() };
+    const flow = getFlow();
+    const session = flow?.user && flow.jwt
+        ? { user: flow.user, jwt: flow.jwt, address: flow.address }
+        : null;
+    return { session };
+}
+/**
+ * Renders the subtree under a request-scoped static Flow on the server and
+ * the seeded browser singleton on the client, so the first client render
+ * matches the SSR HTML and no bootstrap refresh runs while the hydrated JWT
+ * is fresh.
+ */
+export function FlowRoot({ session, autoGuest, host, children, }) {
+    const flow = useMemo(() => typeof window === "undefined"
+        ? createStaticFlow(session, { host })
+        : createFlow({ initialState: session, autoGuest, host }), [session, autoGuest, host]);
+    return _jsx(FlowIdProvider, { flow: flow, children: children });
+}

package/dist/sdk/start/server.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Server half of the TanStack Start integration: the session-route handlers
+ * and the SSR resolve used by the app's `getFlowSession` server fn. Import
+ * only from app-source files the Start compiler splits server-side (the
+ * session route file) — see `@flow-industries/id/start` for the wiring.
+ */
+import type { FlowSessionState, SessionRouteOptions } from "../types";
+/**
+ * The `getFlowSession` server-fn handler: resolves the visitor's session
+ * from the request cookies during SSR. A server-side refresh rotates the
+ * token, so the rotated Set-Cookie values are appended to the response here
+ * rather than left to callers. The audience is pinned by `APP_ORIGIN`
+ * (mandatory behind a TLS-terminating proxy), falling back to the request
+ * origin in dev.
+ */
+export declare function resolveFlowSessionRequest(): Promise<FlowSessionState | null>;
+/**
+ * Route handlers for the app's session route file:
+ * `createFileRoute("/flow/session")({ server: { handlers: flowSessionHandlers() } })`.
+ * The route path must match the client's `sessionPath` (default
+ * `/flow/session`).
+ */
+export declare function flowSessionHandlers(opts?: SessionRouteOptions): {
+    GET: ({ request }: {
+        request: Request;
+    }) => Promise<Response>;
+    POST: ({ request }: {
+        request: Request;
+    }) => Promise<Response>;
+    DELETE: ({ request }: {
+        request: Request;
+    }) => Promise<Response>;
+};

package/dist/sdk/start/server.js

@@ -0,0 +1,35 @@
+/**
+ * Server half of the TanStack Start integration: the session-route handlers
+ * and the SSR resolve used by the app's `getFlowSession` server fn. Import
+ * only from app-source files the Start compiler splits server-side (the
+ * session route file) — see `@flow-industries/id/start` for the wiring.
+ */
+import { getRequestHeader, getRequestUrl, setResponseHeader, } from "@tanstack/react-start/server";
+import { defaultAudience, defaultIdHost } from "../id-host";
+import { resolveSession } from "../server";
+import { handleSessionRequest } from "../session-route";
+/**
+ * The `getFlowSession` server-fn handler: resolves the visitor's session
+ * from the request cookies during SSR. A server-side refresh rotates the
+ * token, so the rotated Set-Cookie values are appended to the response here
+ * rather than left to callers. The audience is pinned by `APP_ORIGIN`
+ * (mandatory behind a TLS-terminating proxy), falling back to the request
+ * origin in dev.
+ */
+export async function resolveFlowSessionRequest() {
+    const audience = defaultAudience(getRequestUrl().origin);
+    const { state, setCookies } = await resolveSession(getRequestHeader("cookie"), { audience, issuerUrl: defaultIdHost(audience) });
+    if (setCookies.length > 0)
+        setResponseHeader("Set-Cookie", setCookies);
+    return state;
+}
+/**
+ * Route handlers for the app's session route file:
+ * `createFileRoute("/flow/session")({ server: { handlers: flowSessionHandlers() } })`.
+ * The route path must match the client's `sessionPath` (default
+ * `/flow/session`).
+ */
+export function flowSessionHandlers(opts = {}) {
+    const handler = ({ request }) => handleSessionRequest(request, opts);
+    return { GET: handler, POST: handler, DELETE: handler };
+}

package/dist/sdk/types/index.d.ts

@@ -5,7 +5,7 @@ export type { Bridge, BridgeParameters, FlowAccount, FlowRemote, FlowRemoteConfi
 export type { Call, ConnectCapabilities, ConnectRequest, ConnectResponse, GuestRequest, GuestResponse, MethodName, MethodParams, MethodResult, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignOutRequest, SignOutResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
 export { getConnectCapabilities, isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
 export type { CreateRoomInput, MyRooms, RoomChannel, RoomDetail, RoomList, RoomMemberEntry, RoomMembers, RoomOccupancy, RoomOwner, RoomPresenceEntry, RoomPresenceSnapshot, RoomRestrictionKind, RoomRole, RoomSummary, RoomSurfaceSettings, RoomsApi, RoomVisibility, UpdateRoomInput, VerifyRoomContext, } from "./rooms";
-export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, FlowState, Listener, LoginOptions, MountProfileOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, RefreshCookieConfig, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
-export type { ResolvedFlowSession, ResolveSessionOptions } from "./server";
+export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, FlowState, Listener, LoginOptions, MountProfileOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
+export type { ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } from "./server";
 export type { CoinAsset, IdentifiedTx, TxApprove, TxConvert, TxSend, TxSwap, } from "./tx";
 export type { ActionDayContext, ActionEventKind, ActionSessionState, ActiveActionResponse, LevelProgress, PublicProfile, XpGrantResult, XpRecentGrant, XpSummary, } from "./xp";

package/dist/sdk/types/sdk.d.ts

@@ -72,13 +72,14 @@ export type CreateFlowOptions = {
      */
     autoGuest?: boolean;
     /**
-     * If true, the JWT and the rotating refresh token are mirrored into
-     * first-party cookies on the app's own origin so the app's server can
-     * resolve the session per-request (see `@flow-industries/id/server`).
-     * Off by default — a backend that never reads them shouldn't start
-     * receiving refresh tokens on every request.
+     * Path of the app's first-party session route (see
+     * `@flow-industries/id/server`). The refresh token lives in an HttpOnly
+     * cookie owned by the app's server; the client resolves, installs, and
+     * revokes the session exclusively through this same-origin route. Override
+     * only when the app cannot claim the default path — the route registration
+     * must use the same value.
      */
-    cookies?: boolean;
+    sessionPath?: string;
     /**
      * Session state resolved server-side (via `resolveSession`) to seed the
      * store synchronously, so the first client render matches the SSR HTML and
@@ -114,10 +115,6 @@ export type FlowCookieNames = {
     jwt: string;
     refresh: string;
 };
-export type RefreshCookieConfig = {
-    name: string;
-    secure: boolean;
-};
 export type LoginOptions = {
     mode?: "iframe" | "popup";
     signUp?: boolean;

package/dist/sdk/types/server.d.ts

@@ -1,5 +1,5 @@
-import type { VerifiedFlowJWT } from "./auth";
-import type { FlowSessionState } from "./sdk";
+import type { FlowCredential, FlowUser, VerifiedFlowJWT } from "./auth";
+import type { Address, FlowSessionState } from "./sdk";
 import type { PublicProfile } from "./xp";
 export type ResolveSessionOptions = {
     /** The calling app's origin, e.g. `https://flow.game` — must match the JWT `aud`. */
@@ -26,3 +26,31 @@ export type ResolvedFlowSession = {
     /** Public profile, only when requested via `profile: true` and resolvable. */
     profile?: PublicProfile;
 };
+export type SessionRouteOptions = {
+    /**
+     * The app's public origin, e.g. `https://flow.game` — the JWT audience and
+     * what cookie names derive from. Defaults to the `APP_ORIGIN` env var, then
+     * the request's own origin (fine in dev; behind a TLS-terminating proxy set
+     * `APP_ORIGIN`).
+     */
+    audience?: string;
+    /** Flow ID origin; defaults per `defaultIdHost` (`FLOW_ID_HOST` on servers). */
+    issuerUrl?: string;
+    /** Route path for `createSessionHandler`'s own path check. */
+    path?: string;
+};
+/**
+ * A session as the session route reports it to the browser client.
+ * `credential`/`address` are present only when the token was rotated
+ * server-side — the rotation response is authoritative for signing state,
+ * while the JWT hot path knows neither and the client must keep what it has.
+ */
+export type SessionRouteSession = {
+    user: FlowUser;
+    jwt: string;
+    credential?: FlowCredential | null;
+    address?: Address | null;
+};
+export type SessionRouteResponse = {
+    state: SessionRouteSession | null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "main": "./dist/sdk/client/index.js",
   "module": "./dist/sdk/client/index.js",
   "types": "./dist/sdk/client/index.d.ts",
@@ -33,6 +33,14 @@
     "./server": {
       "types": "./dist/sdk/server.d.ts",
       "import": "./dist/sdk/server.js"
+    },
+    "./start": {
+      "types": "./dist/sdk/start/index.d.ts",
+      "import": "./dist/sdk/start/index.js"
+    },
+    "./start/server": {
+      "types": "./dist/sdk/start/server.d.ts",
+      "import": "./dist/sdk/start/server.js"
     }
   },
   "files": [
@@ -66,7 +74,8 @@
     "viem": ">=2.47.10",
     "ox": ">=0.14.0",
     "react": ">=18",
-    "@wagmi/core": ">=3.0.0"
+    "@wagmi/core": ">=3.0.0",
+    "@tanstack/react-start": ">=1.168.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -74,6 +83,9 @@
     },
     "@wagmi/core": {
       "optional": true
+    },
+    "@tanstack/react-start": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -83,6 +95,7 @@
     "@react-email/ui": "^6.6.0",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-router-devtools": "^1.160.0",
+    "@tanstack/react-start": "^1.168.28",
     "@tanstack/router-cli": "^1.167.17",
     "@tanstack/router-plugin": "^1.160.0",
     "@types/bun": "latest",