@foir/sdk 0.30.1 → 0.31.0

package/dist/data/builtins.d.ts

@@ -46,6 +46,7 @@
  * against `api-public/internal/schema/field_mapping.go`.
  */
 import type { FoirConnection } from './schema';
+import type { StepReply } from '../runs/step-reply';
 /** A `JSON` scalar. Deliberately not `any`: reading through it needs a check. */
 export type FoirJsonValue = string | number | boolean | null | FoirJsonValue[] | {
     [key: string]: FoirJsonValue;
@@ -84,6 +85,8 @@ export interface Image {
      * `url: String` — so this follows.
      */
     __typename?: 'Image';
+    /** The item's own id when this is an item of a list or an entry of a prose field; null on a plain field's value. */
+    _id: string | null;
     url: string | null;
     width: number | null;
     height: number | null;
@@ -102,6 +105,8 @@ export interface Image {
 }
 export interface Video {
     __typename?: 'Video';
+    /** The item's own id when this is an item of a list or an entry of a prose field; null on a plain field's value. */
+    _id: string | null;
     url: string | null;
     thumbnailUrl: string | null;
     previewUrl: string | null;
@@ -116,6 +121,8 @@ export interface Video {
 }
 export interface FileValue {
     __typename?: 'FileValue';
+    /** The item's own id when this is an item of a list or an entry of a prose field; null on a plain field's value. */
+    _id: string | null;
     url: string | null;
     filename: string | null;
     mimeType: string | null;
@@ -123,6 +130,8 @@ export interface FileValue {
 }
 export interface GeoPoint {
     __typename?: 'GeoPoint';
+    /** The item's own id when this is an item of a list or an entry of a prose field; null on a plain field's value. */
+    _id: string | null;
     lat: number | null;
     lng: number | null;
 }
@@ -157,7 +166,8 @@ export interface ProseSpan {
  */
 export interface Passage {
     __typename?: 'Passage';
-    _key: string | null;
+    /** The passage's own id: minted once, never changed, unique within its record. */
+    _id: string | null;
     kind: string | null;
     token: string | null;
     align: string | null;
@@ -209,30 +219,25 @@ export interface RecordAncestor {
  *
  * # What makes it followable
  *
- * `_targetModelKey` names the model and `_targetId` OR `_targetNaturalKey`
- * identifies the row within it: `foir[_targetModelKey].findUnique({ where: { _id:
- * _targetId } })`. Both identifier shapes are live — on the dev database 101 of
- * 193 stored reference values carry an id and 92 carry a natural key and no id
- * — so a consumer must handle either.
- *
- * `_id` and `_type` are NOT here, and their absence is the correction
- * rather than an omission. They were the wrapper's own metadata: `_id` was the
- * ITEM's id (never the target's, which is why `_targetId` exists separately) and
- * `_type` was the union discriminator, reading `"reference"` on every reference
- * ever stored. The wrapper is gone, so neither field is in the schema, and a
- * consumer selecting them got `undefined` while the types promised a string.
+ * `_targetModelKey` names the model and `_targetId` the row within it:
+ * `foir[_targetModelKey].findUnique({ where: { _id: _targetId } })`. A reference
+ * names its target by id and nothing else.
+ *
+ * `_id` is the entry's own id, never the target's, which is why `_targetId`
+ * exists separately. It is null on a reference field's value, which is not an
+ * entry.
  */
 export interface Reference<TRecord = FoirUnexpandedRecord> {
     __typename?: 'Reference';
+    /** The entry's own id, when the reference is an entry of a prose field. */
+    _id: string | null;
     /** The model to fetch the target from. Null when the target no longer exists. */
     _targetModelKey: string | null;
-    /** The target's id, when the reference stored one. */
+    /** The target's id. */
     _targetId: string | null;
-    /** The target's natural key, when the reference names its target that way. */
-    _targetNaturalKey: string | null;
     /**
      * The resolved target, over the project's `Record` union — every model in the
-     * project. Left as a type parameter so the generated file can name that
+     * project that bears records. Left as a type parameter so the generated file can name that
      * union; the default is the honest answer for a consumer who has not narrowed
      * it.
      */
@@ -397,13 +402,8 @@ export type FoirUnexpandedRecord = FoirDegraded;
  */
 export type FoirVisibility = 'PRIVATE' | 'PUBLIC';
 export type FoirAccessLevel = 'READ' | 'WRITE' | 'DELETE';
-export type FoirAccessSource = 'PUBLIC' | 'OWNER' | 'GRANT' | 'ROLE';
+export type FoirAccessSource = 'OWNER' | 'GRANT' | 'ROLE';
 export type FoirGranteeKind = 'USER';
-/** `myAccess` — this principal's effective access to one record. */
-export interface FoirMyAccess {
-    access: FoirAccessLevel;
-    source: FoirAccessSource;
-}
 export interface FoirAccessGrant {
     access: FoirAccessLevel;
     createdAt: string;
@@ -416,7 +416,7 @@ export interface FoirAccessor {
     granteeKind: FoirGranteeKind;
     source: FoirAccessSource;
 }
-/** `access` — the full ACL of one record. */
+/** `access` — who can reach one record, or one user's access to it. */
 export interface FoirResourceAccess {
     accessors: FoirAccessor[];
     grants: FoirAccessGrant[];
@@ -592,14 +592,17 @@ export interface FoirWriteNoteArgs {
     /** A visitor may write about a record and nothing else. */
     subjectType: FoirNoteSubjectType;
     subjectId: string;
-    /** Required when `subjectType` is `'record'`, refused otherwise. */
+    /**
+     * @deprecated Not read: a note on a record takes the record's own model.
+     * Still accepted so code that sends it keeps working.
+     */
     subjectModelKey?: string;
     body: string;
     /** Reply within an existing thread. Refused where nobody is signed in. */
     parentNoteId?: string;
     /**
-     * Files to submit with this note, already uploaded through
-     * `createFileUpload` / `confirmFileUpload`. Refused where nobody is signed in.
+     * Files to submit with this note, already uploaded through `uploadFile`.
+     * Refused where nobody is signed in.
      *
      * A file this caller cannot read is REFUSED and the note is not written. That
      * is not a rough edge to code around: a create that accepted the note and
@@ -626,14 +629,16 @@ export interface FoirWriteNoteArgs {
 export interface FoirCreateMyNoteArgs {
     subjectType: FoirNoteSubjectType;
     subjectId: string;
-    /** Required when `subjectType` is `'record'`, refused otherwise. */
+    /**
+     * @deprecated Not read: a note on a record takes the record's own model.
+     * Still accepted so code that sends it keeps working.
+     */
     subjectModelKey?: string;
     body: string;
     /** Reply within an existing thread. */
     parentNoteId?: string;
     /**
-     * Files to submit with this note, already uploaded through
-     * `createFileUpload` / `confirmFileUpload`.
+     * Files to submit with this note, already uploaded through `uploadFile`.
      *
      * A file this caller cannot read is REFUSED and the note is not written. That
      * is not a rough edge to code around: a create that accepted the note and
@@ -693,14 +698,35 @@ export interface FoirAgentApproval {
     decision: 'PENDING' | 'APPROVED' | 'DENIED' | 'EXPIRED';
     reason?: string | null;
 }
+/**
+ * An act held for a decision: a step a run holds, or an act proposed on a
+ * note. `myAgentApprovals` lists them and `decideAgentApproval` decides one.
+ */
+export interface FoirAgentHeldAct {
+    /** Pass it to `decideAgentApproval`. */
+    id: string;
+    heldIn: 'RUN' | 'NOTE';
+    /** RUN: the run that holds it. */
+    runId?: string | null;
+    /** NOTE: the note it is held on. */
+    noteId?: string | null;
+    /** The tool, operation or agent it would call, by its name. */
+    action: string;
+    /** What it would be called with. */
+    input?: unknown;
+    approval?: FoirAgentApproval | null;
+    requestedBy?: string | null;
+    /** ISO-8601. */
+    createdAt?: string | null;
+}
 /** One step of a run: a model turn, a tool call, a check, or a child agent. */
 export interface FoirAgentRunNode {
     id: string;
     parentId?: string | null;
     /**
      * PAGE_TOOL is a call to a tool the caller's page offered with the message,
-     * HELD until the page answers it with `answerPageTool`; DATA is data sent to
-     * the app's components, delivered as a DATA event.
+     * HELD until the page answers it with its `reply`; DATA is data sent to the
+     * app's components, delivered as a DATA event.
      */
     kind: 'AGENT' | 'OPERATION' | 'VERB' | 'MCP_TOOL' | 'MODEL_TURN' | 'CHECK' | 'PAGE_TOOL' | 'DATA';
     /** The tool, operation or agent the step is, by its key. */
@@ -714,6 +740,11 @@ export interface FoirAgentRunNode {
     startedAt?: string | null;
     /** ISO-8601. */
     completedAt?: string | null;
+    /**
+     * A HELD PAGE_TOOL step, for the run's own caller: how the page answers it,
+     * with `replyToStep`. Nobody else is handed one.
+     */
+    reply?: StepReply | null;
 }
 /**
  * A run of an agent: its answer, once given, and every step it took. A refusal
@@ -793,7 +824,7 @@ export interface FoirStartAgentRunArgs {
     /**
      * Tools of the caller's own page the agent may call during this run, for
      * an agent that allows the page's tools. A call is HELD until the page
-     * answers it with `answerPageTool`. At most 20. `foirChatTransport`'s
+     * answers it with its `reply`. At most 20. `foirChatTransport`'s
      * `pageTools` sends these and answers the calls for you.
      */
     pageTools?: FoirPageToolOffer[];

package/dist/data/index.d.ts

@@ -59,7 +59,7 @@ export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
 export type { FoirFieldMark, FoirFieldMarkAttributes, FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirWriteNoteArgs, FoirUserNote, FoirUserNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirAgentApproval, FoirAgentAttachment, FoirAgentAttachmentUpload, FoirAgentRun, FoirAgentRunNode, FoirAgentRunStatus, FoirAgentThread, FoirAgentThreadMessage, FoirAgentThreadsResult, FoirMcpConnection, FoirStartAgentRunArgs, FoirPageToolOffer, FoirCreateAgentAttachmentArgs, FoirMessageTag, FoirMessageTagKind, FoirNoteConfig, FoirNoteReceipt, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirWriteNoteArgs, FoirUserNote, FoirUserNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyNotesArgs, FoirMyNotesResult, FoirAgentApproval, FoirAgentAttachment, FoirAgentAttachmentUpload, FoirAgentRun, FoirAgentHeldAct, FoirAgentRunNode, FoirAgentRunStatus, FoirAgentThread, FoirAgentThreadMessage, FoirAgentThreadsResult, FoirMcpConnection, FoirStartAgentRunArgs, FoirPageToolOffer, FoirCreateAgentAttachmentArgs, FoirMessageTag, FoirMessageTagKind, FoirNoteConfig, FoirNoteReceipt, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
  * Pre-rename spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each
@@ -82,6 +82,6 @@ export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmitt
 export { FoirDecimal, decimal } from './decimal';
 export type { FoirDecimalDivOptions, FoirDecimalInput, FoirDecimalRounding, } from './decimal';
 export { FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, FOIR_VISITOR_IP_HEADER, stepUpRequired, } from '../transport/foir-http';
-export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, FoirStepUp, FoirVisitor, FoirVisitorSource, } from '../transport/foir-http';
+export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, FoirStepUp, FoirStepUpAsk, FoirVisitor, FoirVisitorSource, } from '../transport/foir-http';
 export { askAgent, uploadAgentFile, visitorToken } from './agents';
 export type { AgentReply, AskAgentOptions, FoirAgentFile, FoirAgentFilesClient, FoirAgentsClient } from './agents';

package/dist/data/manifest.d.ts

@@ -97,7 +97,7 @@ export interface FoirManifestOp {
      *
      * The model's own `selection` answers for `findUnique` and for nothing else:
      * `findMany` returns a connection OVER the model, `search` returns a wrapper
-     * CARRYING it, `delete` returns `Boolean!`, and `myAccess` returns a payload
+     * CARRYING it, `delete` returns `Boolean!`, and `access` returns a payload
      * that is not the model in any sense. A consumer that bridged that gap by
      * knowing from the OP NAME which shape to print was carrying a schema under
      * another name.

package/dist/data/schema.d.ts

@@ -151,7 +151,7 @@
  *      (`findUnique`, `findMine`).
  *    - `connection` — a Relay connection over the model (`findMany`).
  *    - `list` — a plain array of the model.
- *    - `opaque` — the op does not return the model at all (`myAccess`). Its
+ *    - `opaque` — the op does not return the model at all (`access`). Its
  *      `type` is used verbatim and `include`/`omit` are not offered.
  *
  * 7. **Unions are emitted statically.** A polymorphic field's type is written

package/dist/data/selection.d.ts

@@ -274,9 +274,9 @@ type MemberOf<U, T> = Extract<U, {
  *
  * `__typename` is excluded because it is not optional: the printer emits it at
  * the union level whatever the selection says, so offering it would suggest a
- * choice that does not exist. Block-meta keys (`_id`, `_key`, `_type`,
- * `_label`) ARE offered — unlike a record's `_id` the server does not force
- * them inside a fragment, so naming them is the only way to keep them.
+ * choice that does not exist. An entry's own `_id` IS offered — unlike a
+ * record's `_id` the server does not force it inside a fragment, so naming it is
+ * the only way to keep it.
  */
 type MemberKeys<U, T> = Exclude<Extract<keyof MemberOf<U, T>, string>, '__typename'>;
 /**

package/dist/data.js

@@ -14,8 +14,11 @@ function stepUpRequired(error) {
   if (!(error instanceof FoirRequestError)) return null;
   for (const item of error.graphQLErrors ?? []) {
     if (item.extensions?.code !== "STEP_UP_REQUIRED") continue;
-    const asked = item.extensions.stepUp;
-    if (asked === "second_factor" || asked === "sign_in_method") return asked;
+    const kind = item.extensions.stepUp;
+    if (kind === "proof" || kind === "second_factor" || kind === "sign_in_method") {
+      const url = item.extensions.stepUpUrl;
+      return { kind, url: typeof url === "string" && url !== "" ? url : null };
+    }
   }
   return null;
 }

package/dist/next/index.d.ts

@@ -13,7 +13,7 @@
  */
 export { createFoirCookieAdapter, foirCookieName, } from './cookieAdapter';
 export type { FoirCookieStore, CookieAdapterOptions } from './cookieAdapter';
-export { getFoirSession, getFoirToken, foirSignOut, foirSignInWithPassword, foirRegisterWithPassword, foirSignInWithOtp, completeFoirProviderLogin, } from './session';
+export { getFoirSession, getFoirToken, foirSignOut, foirSignInWithPassword, foirSignUpWithPassword, foirSignInWithOtp, startFoirProviderSignIn, finishFoirProviderSignIn, } from './session';
 export { readFoirCacheTags, foirCacheTags, createFoirTaggingFetch, foirTagsForRecordEvent, revalidateFoirRecordEvent, FOIR_SURROGATE_KEY_HEADER, FOIR_NEXT_TAG_MAX_ITEMS, FOIR_NEXT_TAG_MAX_LENGTH, FOIR_UNTAGGED_TAG, } from './cacheTags';
 export type { FoirHeaderSource, FoirCacheTags, FoirCacheTagsOptions, FoirTaggingReport, FoirTaggingFetchOptions, FoirRecordChange, } from './cacheTags';
 export { createFoirMiddleware } from './middleware';

package/dist/next/session.d.ts

@@ -1,4 +1,4 @@
-import type { FoirUser } from '../auth';
+import type { FoirSignInStep, FoirUser, ProviderSignInInput } from '../auth';
 import type { FoirEnv } from '../graphql/foir-request';
 import type { CookieAdapterOptions, FoirCookieStore } from './cookieAdapter';
 /**
@@ -28,25 +28,41 @@ interface PasswordArgs {
 /** Password sign-in in a route handler; persists the session to cookies. */
 export declare function foirSignInWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirUser>;
 /**
- * Start a sign-up in a route handler: the address is mailed a code, and
- * {@link foirSignInWithOtp} with it finishes the account and persists the
+ * Start a sign-up in a route handler: the address is mailed a code. Keep the
+ * step this answers (in the form, or a cookie) for {@link foirSignInWithOtp},
+ * which brings the code back to it, finishes the account and persists the
  * session to cookies.
  */
-export declare function foirRegisterWithPassword({ env, email, password, }: Pick<PasswordArgs, 'env' | 'email' | 'password'>): Promise<void>;
-/** Complete an OTP sign-in in a route handler; persists the session to cookies. */
-export declare function foirSignInWithOtp({ env, store, email, otp, cookieOptions, }: {
+export declare function foirSignUpWithPassword({ env, email, password, }: Pick<PasswordArgs, 'env' | 'email' | 'password'>): Promise<FoirSignInStep>;
+/**
+ * Complete a code sign-in in a route handler: bring the code back to the step
+ * `requestOTP` or {@link foirSignUpWithPassword} answered. Persists the
+ * session to cookies.
+ */
+export declare function foirSignInWithOtp({ env, store, step, otp, cookieOptions, }: {
     env: FoirEnv;
     store: FoirCookieStore;
-    email: string;
+    step: FoirSignInStep;
     otp: string;
     cookieOptions?: CookieAdapterOptions['cookieOptions'];
 }): Promise<FoirUser>;
 /**
- * Complete a provider (OAuth/OIDC) login in your callback route handler:
- * exchange the `code` + `state` for tokens and persist them to the session
- * cookies. Returns the user.
+ * Start a provider (OAuth/OIDC) sign-in in a route handler: answers where to
+ * send the browser, and keeps the step its finish is brought back to in the
+ * session cookies for {@link finishFoirProviderSignIn}.
+ */
+export declare function startFoirProviderSignIn(opts: {
+    env: FoirEnv;
+    store: FoirCookieStore;
+    input: ProviderSignInInput;
+    cookieOptions?: CookieAdapterOptions['cookieOptions'];
+}): Promise<string | null>;
+/**
+ * Finish a provider (OAuth/OIDC) sign-in in your callback route handler:
+ * bring the `code` + `state` back to the step {@link startFoirProviderSignIn}
+ * kept, and persist the session to cookies. Returns the user.
  */
-export declare function completeFoirProviderLogin(opts: {
+export declare function finishFoirProviderSignIn(opts: {
     env: FoirEnv;
     store: FoirCookieStore;
     providerKey: string;

package/dist/next.js

@@ -949,7 +949,7 @@ async function fetchFoirManifest(config, options = {}) {
 
 // src/auth/ops.ts
 var AUTH_OPS = {
-  // Pre-credential reads a login screen renders itself from.
+  // Pre-credential reads a sign-in screen renders itself from.
   authConfig: "authConfig",
   authProviders: "authProviders",
   defaultAuthProvider: "defaultAuthProvider",
@@ -961,17 +961,15 @@ var AUTH_OPS = {
   // they hold. `./access` reads it.
   whoami: "whoami",
   // Methods.
-  login: "login",
+  signIn: "signIn",
   register: "register",
   requestOTP: "requestOTP",
-  loginWithOTP: "loginWithOTP",
   // Session lifecycle.
   refreshToken: "refreshToken",
-  logout: "logout",
+  signOut: "signOut",
   joinWaitlist: "joinWaitlist",
   // Password management and account lifecycle.
   requestPasswordReset: "requestPasswordReset",
-  resetPassword: "resetPassword",
   updatePassword: "updatePassword",
   deleteMyAccount: "deleteMyAccount",
   // Ending their own membership where the request stands.
@@ -985,10 +983,10 @@ var AUTH_OPS = {
   mySessions: "mySessions",
   endMySession: "endMySession",
   signOutEverywhere: "signOutEverywhere",
-  // Their email addresses: one added is kept once the code it was sent proves it.
+  // Their email addresses: one added is kept once the code it was sent comes
+  // back on the step addMyAddress answers, on its own route (proveMyAddress).
   myAddresses: "myAddresses",
   addMyAddress: "addMyAddress",
-  proveMyAddress: "proveMyAddress",
   makeMyAddressPrimary: "makeMyAddressPrimary",
   removeMyAddress: "removeMyAddress",
   // A copy of their own data.
@@ -999,10 +997,8 @@ var AUTH_OPS = {
   disconnectSignInMethod: "disconnectSignInMethod",
   // Their second factors. A change needs one proven first, by a step-up.
   myFactors: "myFactors",
-  beginStepUp: "beginStepUp",
-  completeStepUp: "completeStepUp",
+  stepUp: "stepUp",
   beginFactorEnrollment: "beginFactorEnrollment",
-  completeFactorEnrollment: "completeFactorEnrollment",
   removeFactor: "removeFactor",
   renameFactor: "renameFactor",
   makeRecoveryCodes: "makeRecoveryCodes",
@@ -1016,13 +1012,7 @@ var AUTH_OPS = {
   // Founding one. Present in a manifest only when the project opted in.
   registerOrganization: "registerOrganization",
   // External identity providers.
-  loginWithProvider: "loginWithProvider",
-  providerCallback: "providerCallback",
-  providerVerifyOTP: "providerVerifyOTP",
-  // A provider sign-in that names an address somebody already holds, waiting
-  // for the code sent to it.
-  confirmProviderLink: "confirmProviderLink",
-  resendProviderLinkCode: "resendProviderLinkCode"
+  signInWithProvider: "signInWithProvider"
 };
 function authClientConfig(env, options) {
   const apiKey = resolveFoirApiKey(env);
@@ -1082,22 +1072,88 @@ function stripUndefined(args) {
   return out;
 }
 
+// src/auth/steps.ts
+async function postSignInStep(env, path, body, stepToken) {
+  const apiUrl = env.PLATFORM_API_URL;
+  if (!apiUrl) {
+    throw new FoirRequestError("[foir] no api url configured: set PLATFORM_API_URL");
+  }
+  const headers = { "Content-Type": "application/json" };
+  if (stepToken) headers["X-Foir-Token"] = stepToken;
+  const res = await fetch(foirApiEndpoint(apiUrl, path), {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message = typeof data.error === "string" ? data.error : `[foir] POST ${path} failed: HTTP ${res.status}`;
+    const code = typeof data.code === "string" ? data.code : void 0;
+    const extensions = {};
+    if (code) extensions.code = code;
+    if (data.signIn && typeof data.signIn === "object") extensions.signIn = data.signIn;
+    if (data.providerSignIn && typeof data.providerSignIn === "object") extensions.providerSignIn = data.providerSignIn;
+    throw new FoirRequestError(message, {
+      status: res.status,
+      graphQLErrors: Object.keys(extensions).length > 0 ? [{ message, extensions }] : void 0
+    });
+  }
+  return data;
+}
+
 // src/auth/auth.ts
 var TOKEN_KEY = "foir:token";
 var REFRESH_KEY = "foir:refreshToken";
 var USER_ID_KEY = "foir:userId";
 var EMAIL_KEY = "foir:email";
-async function login(env, vars) {
-  return authOp(env, AUTH_OPS.login, vars);
+async function codeSignIn(env, vars) {
+  const signedIn = await postSignInStep(env, `/v1/sign-ins/${encodeURIComponent(vars.step.id)}/code`, { code: vars.otp }, vars.step.token);
+  return {
+    token: signedIn.accessToken ?? "",
+    refreshToken: signedIn.refreshToken ?? "",
+    userId: signedIn.user?.id ?? "",
+    email: signedIn.user?.email ?? ""
+  };
 }
-async function register(env, vars) {
-  return authOp(env, AUTH_OPS.register, vars);
+async function signInWithProvider(adapter, env, input) {
+  const started = await authOp(
+    env,
+    AUTH_OPS.signInWithProvider,
+    { input }
+  );
+  if (started.step) await adapter.set(PROVIDER_STEP_KEY, JSON.stringify(started.step));
+  else await adapter.unset(PROVIDER_STEP_KEY);
+  return { redirectUrl: started.redirectUrl ?? null };
+}
+async function finishProviderSignIn(adapter, env, input) {
+  const step = await keptProviderStep(adapter, "no provider sign-in was started here: start one before finishing it");
+  return signedInOnStep(adapter, env, step, "provider", {
+    providerKey: input.providerKey,
+    code: input.code,
+    state: input.state
+  });
 }
-async function loginWithOTP(env, vars) {
-  return authOp(env, AUTH_OPS.loginWithOTP, vars);
+var PROVIDER_STEP_KEY = "foir:providerStep";
+async function keptProviderStep(adapter, missing) {
+  const raw = await adapter.get(PROVIDER_STEP_KEY);
+  if (raw) {
+    try {
+      const step = JSON.parse(raw);
+      if (typeof step.id === "string" && typeof step.token === "string") return step;
+    } catch {
+    }
+  }
+  throw new Error(`[foir] ${missing}`);
 }
-async function providerCallback(env, input) {
-  return authOp(env, AUTH_OPS.providerCallback, { input });
+async function signedInOnStep(adapter, env, step, route, body) {
+  const signedIn = await postSignInStep(env, `/v1/sign-ins/${encodeURIComponent(step.id)}/${route}`, body, step.token);
+  await adapter.unset(PROVIDER_STEP_KEY);
+  return saveSession(adapter, {
+    token: signedIn.accessToken ?? "",
+    refreshToken: signedIn.refreshToken ?? "",
+    userId: signedIn.userId ?? "",
+    email: signedIn.email ?? ""
+  });
 }
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
@@ -1125,13 +1181,13 @@ async function getSessionUser(adapter) {
   return { id, email: email ?? "" };
 }
 async function signInWithPassword(adapter, env, vars) {
-  return saveSession(adapter, await login(env, vars));
+  return saveSession(adapter, await authOp(env, AUTH_OPS.signIn, vars));
 }
 async function signUpWithPassword(env, vars) {
-  await register(env, vars);
+  return authOp(env, AUTH_OPS.register, vars);
 }
 async function signInWithOTP(adapter, env, vars) {
-  return saveSession(adapter, await loginWithOTP(env, vars));
+  return saveSession(adapter, await codeSignIn(env, vars));
 }
 
 // src/next/session.ts
@@ -1156,7 +1212,7 @@ function foirSignInWithPassword({
     password
   });
 }
-function foirRegisterWithPassword({
+function foirSignUpWithPassword({
   env,
   email,
   password
@@ -1166,25 +1222,26 @@ function foirRegisterWithPassword({
 function foirSignInWithOtp({
   env,
   store,
-  email,
+  step,
   otp,
   cookieOptions
 }) {
   return signInWithOTP(createFoirCookieAdapter(store, { cookieOptions }), env, {
-    email,
+    step,
     otp
   });
 }
-async function completeFoirProviderLogin(opts) {
-  const result = await providerCallback(opts.env, {
+async function startFoirProviderSignIn(opts) {
+  const adapter = createFoirCookieAdapter(opts.store, { cookieOptions: opts.cookieOptions });
+  return (await signInWithProvider(adapter, opts.env, opts.input)).redirectUrl;
+}
+async function finishFoirProviderSignIn(opts) {
+  const adapter = createFoirCookieAdapter(opts.store, { cookieOptions: opts.cookieOptions });
+  return finishProviderSignIn(adapter, opts.env, {
     providerKey: opts.providerKey,
     code: opts.code,
     state: opts.state
   });
-  return saveSession(
-    createFoirCookieAdapter(opts.store, { cookieOptions: opts.cookieOptions }),
-    result
-  );
 }
 
 // src/live/events.ts
@@ -1304,19 +1361,20 @@ export {
   FOIR_NEXT_TAG_MAX_LENGTH,
   FOIR_SURROGATE_KEY_HEADER,
   FOIR_UNTAGGED_TAG,
-  completeFoirProviderLogin,
   createFoirCookieAdapter,
   createFoirMiddleware,
   createFoirTaggingFetch,
+  finishFoirProviderSignIn,
   foirCacheTags,
   foirCookieName,
-  foirRegisterWithPassword,
   foirSignInWithOtp,
   foirSignInWithPassword,
   foirSignOut,
+  foirSignUpWithPassword,
   foirTagsForRecordEvent,
   getFoirSession,
   getFoirToken,
   readFoirCacheTags,
-  revalidateFoirRecordEvent
+  revalidateFoirRecordEvent,
+  startFoirProviderSignIn
 };