@foir/sdk 0.5.0 → 0.8.0

package/dist/react/FoirFeedback.d.ts

@@ -0,0 +1,62 @@
+import type { FoirCustomerNote, FoirSubject, FoirSubjectRegistry } from '../data';
+import { type FoirFeedbackClient } from './feedback-notes';
+export type { FoirFeedbackClient } from './feedback-notes';
+export interface FoirFeedbackProps {
+    /**
+     * The data client the page reads through — the one you passed the subject
+     * registry to. Its `notes` namespace is what a submission goes to, and its
+     * `files` namespace is what a screenshot is uploaded through.
+     */
+    client: FoirFeedbackClient;
+    /**
+     * The registry from `createFoirSubjectRegistry()`, the same object you passed
+     * to `createFoirClient({ subjects })`.
+     *
+     * Passed rather than discovered, because the registry is deliberately an
+     * object the host owns and not a flag the client turns on — see the registry's
+     * own header for why a list of what a page fetched is not the SDK's to hand
+     * out. Omit it and the widget has no subject unless you pass one.
+     */
+    subjects?: FoirSubjectRegistry;
+    /**
+     * Pin what the feedback is about, overriding the registry.
+     *
+     * `null` states there is nothing to comment on, which is a different claim
+     * from omitting the prop and worth being able to make: a checkout step or a
+     * dashboard renders no record and should say so rather than inherit whatever
+     * the previous page fetched.
+     */
+    subject?: FoirSubject | null;
+    /**
+     * What to call the subject on screen, overriding the label the registry
+     * resolved. Omit both and the widget shows no name at all.
+     */
+    label?: string;
+    /** The disclosure button's text. Default `Feedback`. */
+    triggerLabel?: string;
+    /** The panel's heading. Default `Send feedback`. */
+    title?: string;
+    /** The composer's placeholder. Default `What would you like to tell us?`. */
+    placeholder?: string;
+    /** Start with the panel open. Default false. */
+    defaultOpen?: boolean;
+    /**
+     * Called when the visitor has to sign in first. Given a handler, the widget
+     * renders a button that calls it; given none, it says so and stops.
+     */
+    onSignIn?: () => void;
+    /** Called with the note once it is written. */
+    onSubmitted?: (note: FoirCustomerNote) => void;
+    /**
+     * Called with anything that failed. The widget also logs it — this is for
+     * routing it into your own error reporting, not for making it visible.
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Style it yourself. Passing a class turns OFF the built-in inline styles
+     * entirely, so the `data-foir-feedback-*` attributes below are yours to target
+     * without fighting anything.
+     */
+    className?: string;
+}
+export declare function FoirFeedback({ client, subjects, subject, label, triggerLabel, title, placeholder, defaultOpen, onSignIn, onSubmitted, onError, className, }: FoirFeedbackProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/FoirProvider.d.ts

@@ -0,0 +1,116 @@
+import type { ReactNode } from 'react';
+import type { AuthProviderPublic, FoirCustomer, FoirSessionConfig, SessionAdapter } from '../auth';
+import type { ProviderCallbackInput, ProviderLoginInput } from '../auth';
+import type { FoirEnv } from '../graphql/foir-request';
+/** Where the session hydration stands. */
+export type FoirStatus = 'loading' | 'authenticated' | 'unauthenticated';
+/** The full context value. Read it through the hooks below, not directly. */
+export interface FoirContextValue {
+    status: FoirStatus;
+    customer: FoirCustomer | null;
+    /** The API config; exposed so advanced consumers can call `@foir/sdk/auth` directly. */
+    env: FoirEnv;
+    /** The session store backing this provider. */
+    adapter: SessionAdapter;
+    signIn(vars: {
+        email: string;
+        password: string;
+    }): Promise<FoirCustomer>;
+    register(vars: {
+        email: string;
+        password: string;
+    }): Promise<FoirCustomer>;
+    requestOtp(email: string): Promise<boolean>;
+    signInWithOtp(vars: {
+        email: string;
+        otp: string;
+    }): Promise<FoirCustomer>;
+    /** Start a provider (OAuth/OIDC) login. Redirect providers navigate away. */
+    signInWithProvider(providerKey: string, opts?: Omit<ProviderLoginInput, 'providerKey'>): Promise<void>;
+    /** Complete a provider login from your callback route (code + state). */
+    completeProviderLogin(input: Omit<ProviderCallbackInput, 'providerKey'> & {
+        providerKey: string;
+    }): Promise<FoirCustomer>;
+    signOut(): Promise<void>;
+    /** Rotate the access token; returns false (and signs out) if it can't. */
+    refresh(): Promise<boolean>;
+    /** The current access token, or null when signed out. */
+    getToken(): Promise<string | null>;
+    /** The project's configured auth providers (for OAuth buttons). */
+    getProviders(): Promise<AuthProviderPublic[]>;
+    /**
+     * In `hostedSession` mode, where to send the browser to sign in — sign-in is a
+     * redirect to your Foir login domain, not an in-page form. Null in token mode,
+     * where you call {@link FoirContextValue.signIn} instead.
+     */
+    hostedSignInUrl: ((returnTo?: string) => string) | null;
+}
+export interface FoirProviderProps {
+    /** API config: `{ PLATFORM_API_URL, PLATFORM_API_KEY }` (a publishable `pk_` key). */
+    env: FoirEnv;
+    /** Session store for token mode. Defaults to a browser localStorage adapter. */
+    adapter?: SessionAdapter;
+    /**
+     * Opt into Foir-hosted first-party sessions: the durable credential is an
+     * HttpOnly cookie on your own domain and the access token lives only in
+     * memory, so nothing authentication-related is reachable from JS. This is the
+     * secure default for a backend-less SPA, and it REPLACES `adapter` — pass one
+     * or the other, not both.
+     *
+     * Requires a verified custom login domain sharing a registrable domain with
+     * your app (`app.acme.com` + `login.acme.com`). Sign-in becomes a redirect to
+     * {@link FoirContextValue.hostedSignInUrl}; the password/OTP/provider actions
+     * do not apply and will throw.
+     */
+    hostedSession?: Omit<FoirSessionConfig, 'onSignOut'>;
+    children: ReactNode;
+}
+/**
+ * Provides Foir customer auth to a React tree. Hydrates the session on mount,
+ * then exposes the current customer and sign-in/out actions through
+ * {@link useFoirSession}, {@link useFoirUser}, and {@link useFoirAuth}.
+ *
+ * Two session models:
+ *
+ *   default          tokens in a `SessionAdapter` (localStorage unless you pass
+ *                    your own). Simple, but a refresh token sits in JS.
+ *   `hostedSession`  Foir-hosted first-party cookie; the bearer never leaves
+ *                    memory. Needs a custom login domain. Prefer this.
+ */
+export declare function FoirProvider({ env, adapter, hostedSession, children, }: FoirProviderProps): import("react/jsx-runtime").JSX.Element;
+/** The current session state. */
+export interface FoirSession {
+    status: FoirStatus;
+    customer: FoirCustomer | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+}
+/** Read the current session status and customer. */
+export declare function useFoirSession(): FoirSession;
+/** The signed-in customer (`{ id, email }`), or null. */
+export declare function useFoirUser(): FoirCustomer | null;
+/** The sign-in / sign-out actions. */
+export declare function useFoirAuth(): {
+    signIn: (vars: {
+        email: string;
+        password: string;
+    }) => Promise<FoirCustomer>;
+    register: (vars: {
+        email: string;
+        password: string;
+    }) => Promise<FoirCustomer>;
+    requestOtp: (email: string) => Promise<boolean>;
+    signInWithOtp: (vars: {
+        email: string;
+        otp: string;
+    }) => Promise<FoirCustomer>;
+    signInWithProvider: (providerKey: string, opts?: Omit<ProviderLoginInput, "providerKey">) => Promise<void>;
+    completeProviderLogin: (input: Omit<ProviderCallbackInput, "providerKey"> & {
+        providerKey: string;
+    }) => Promise<FoirCustomer>;
+    signOut: () => Promise<void>;
+    refresh: () => Promise<boolean>;
+    getToken: () => Promise<string | null>;
+    getProviders: () => Promise<AuthProviderPublic[]>;
+    hostedSignInUrl: ((returnTo?: string) => string) | null;
+};

package/dist/react/OAuthButtons.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { AuthProviderPublic } from '../auth';
+export interface OAuthButtonsProps {
+    /** Passed to the provider login (where the callback returns the user). */
+    returnTo?: string;
+    /** Override the provider's default redirect URI (must be allow-listed). */
+    redirectUri?: string;
+    /** Filter which providers render (defaults to every redirect-capable one). */
+    filter?(provider: AuthProviderPublic): boolean;
+    /** Render your own button. Receives the provider and a click handler. */
+    children?(provider: AuthProviderPublic, signIn: () => void): ReactNode;
+    className?: string;
+    onError?(error: unknown): void;
+}
+/**
+ * Renders a sign-in button per configured OAuth/OIDC/SAML provider. Clicking a
+ * button starts the provider login and (for redirect flows) navigates away.
+ * Pass a `children` render prop to fully control the button markup.
+ */
+export declare function OAuthButtons({ returnTo, redirectUri, filter, children, className, onError, }: OAuthButtonsProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/react/SignIn.d.ts

@@ -0,0 +1,22 @@
+import type { FoirCustomer } from '../auth';
+export interface SignInProps {
+    /** `password` (default) or `otp` (email one-time code). Ignored when `hostedUrl` is set. */
+    method?: 'password' | 'otp';
+    /** Render a single button that redirects to a hosted login page instead of an embedded form. */
+    hostedUrl?: string;
+    /** Show OAuth provider buttons below the form. Default true. */
+    oauth?: boolean;
+    /** Navigate here after a successful sign-in. */
+    afterSignInUrl?: string;
+    /** Called with the customer on a successful sign-in (before any redirect). */
+    onSignIn?(customer: FoirCustomer): void;
+    className?: string;
+}
+/**
+ * A drop-in customer sign-in. Renders an email/password (or OTP) form and,
+ * unless disabled, OAuth provider buttons. Set `hostedUrl` to instead render a
+ * button that redirects to a hosted login page. All state is handled through
+ * {@link FoirProvider}; on success it calls `onSignIn` and optionally navigates
+ * to `afterSignInUrl`.
+ */
+export declare function SignIn({ method, hostedUrl, oauth, afterSignInUrl, onSignIn, className, }: SignInProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/UserButton.d.ts

@@ -0,0 +1,13 @@
+export interface UserButtonProps {
+    /** Called after a successful sign-out. */
+    afterSignOut?(): void;
+    /** Navigate here after sign-out. */
+    afterSignOutUrl?: string;
+    className?: string;
+}
+/**
+ * A minimal signed-in affordance: the customer's email plus a sign-out button.
+ * Renders nothing when signed out. Style it via `className` (the default is an
+ * unopinionated inline layout).
+ */
+export declare function UserButton({ afterSignOut, afterSignOutUrl, className }: UserButtonProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/react/feedback-notes.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The non-visual half of `<FoirFeedback>`: reading the notes surface, uploading
+ * an attachment, and telling one refusal from another.
+ *
+ * Separate from the component because none of it is React. A namespace op
+ * answers `unknown` — the manifest publishes root field NAMES and no result
+ * shape (see `data/selection.ts`) — so every response here has to be read rather
+ * than cast, and reading is the part worth testing on its own.
+ */
+import type { FoirCustomerNote, FoirNoteConfig, FoirSubject } from '../data';
+import type { FoirScreenCapture } from '../media/screen-capture';
+/**
+ * The client the widget needs, and no more of it.
+ *
+ * Structural rather than `FoirClient<S>`, for two reasons. `FoirClient` is
+ * generic in the caller's generated schema, so naming it here would force the
+ * component's props to be generic in a parameter nothing else reads. And what
+ * the widget actually depends on is three root fields — narrowing to them means
+ * a client whose key cannot reach `files` still satisfies this type, which is
+ * the honest shape: a project with screenshots off never uploads anything.
+ *
+ * The signatures are the ones `foir types` emits for every namespace op —
+ * `Record<string, unknown>` in, `unknown` out — so a real generated client
+ * assigns to this without a cast. `react/__tests__/feedback.test-d.ts` pins that.
+ */
+export interface FoirFeedbackClient {
+    readonly ns: {
+        readonly notes: {
+            noteConfig(args?: Record<string, unknown>): Promise<unknown>;
+            createMyNote(args?: Record<string, unknown>): Promise<unknown>;
+        };
+        /**
+         * Absent on a credential without the files scopes, which is why it is
+         * optional. Screenshot capture is the only thing that reaches it.
+         */
+        readonly files?: {
+            createFileUpload(args?: Record<string, unknown>): Promise<unknown>;
+            confirmFileUpload(args?: Record<string, unknown>): Promise<unknown>;
+        };
+    };
+}
+/**
+ * Why a call to the notes surface was refused, when the refusal is one the
+ * widget can name.
+ *
+ * The distinction earns its place because the three have different audiences.
+ * `signIn` is the visitor's to fix. `scope` is the OPERATOR's — a role that does
+ * not grant `notes:write` produces `missing required scope: notes:write`, which
+ * reads like a bad API key and is not one; the key is fine and the customer's
+ * role is short a capability. `other` is everything the widget will not pretend
+ * to understand.
+ */
+export type FoirFeedbackFault = {
+    kind: 'signIn';
+} | {
+    kind: 'scope';
+    scope: string;
+} | {
+    kind: 'other';
+};
+/**
+ * Read the refusal, if it is one of the two the widget can act on.
+ *
+ * Matched on the platform's own sentences rather than on an error code, because
+ * these two arrive as plain GraphQL errors with no `extensions.code` to read.
+ * Both the wrapper's message and every individual GraphQL error are scanned: the
+ * transport joins them into one string on the way out, but a partial-error
+ * envelope keeps them apart, and only one of the two forms is guaranteed.
+ */
+export declare function classifyNotesFault(err: unknown): FoirFeedbackFault;
+/**
+ * `noteConfig`, read.
+ *
+ * Throws on a shape it does not recognise rather than defaulting
+ * `screenshotsEnabled` to false. Defaulting would be the quiet version of a
+ * project's setting being ignored: the offer would disappear from every surface
+ * at once and the only symptom would be a missing button.
+ */
+export declare function readNoteConfig(client: FoirFeedbackClient): Promise<FoirNoteConfig>;
+/** What one submission carries. */
+export interface FoirFeedbackSubmission {
+    /**
+     * What the note is about. Always a RECORD subject: the registry only ever
+     * names records, and a host pinning one names a record too.
+     */
+    subject: FoirSubject;
+    body: string;
+    /** The still the visitor chose to attach, or null. */
+    screenshot: FoirScreenCapture | null;
+    /** Injectable for the presigned PUT. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Upload the attachment (if there is one), then write the note.
+ *
+ * In that order, and with the upload failing the whole submission rather than
+ * being skipped. A note that arrived without the picture the visitor attached is
+ * worse than one that did not arrive: they have no way to tell, and the thing
+ * they wrote ("as you can see in the screenshot") stops making sense.
+ */
+export declare function submitFeedbackNote(client: FoirFeedbackClient, submission: FoirFeedbackSubmission): Promise<FoirCustomerNote>;

package/dist/react/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@foir/sdk/react` — drop-in React components for Foir customers.
+ *
+ * Wrap your app in `<FoirProvider>`, then read the session with
+ * `useFoirSession` / `useFoirUser` and drive it with `useFoirAuth` — or drop in
+ * the `<SignIn>`, `<OAuthButtons>`, and `<UserButton>` components. Built entirely
+ * on `@foir/sdk/auth`; `react` is the only peer dependency.
+ *
+ * `<FoirFeedback>` is the annotation half: a feedback widget that anchors to the
+ * RECORD the page was rendered from rather than to its URL. It takes the data
+ * client from `@foir/sdk/data` and the subject registry you built for it.
+ */
+export { FoirProvider, useFoirSession, useFoirUser, useFoirAuth, } from './FoirProvider';
+export type { FoirProviderProps, FoirContextValue, FoirSession, FoirStatus, } from './FoirProvider';
+export { SignIn } from './SignIn';
+export type { SignInProps } from './SignIn';
+export { OAuthButtons } from './OAuthButtons';
+export type { OAuthButtonsProps } from './OAuthButtons';
+export { UserButton } from './UserButton';
+export type { UserButtonProps } from './UserButton';
+export { FoirFeedback } from './FoirFeedback';
+export type { FoirFeedbackProps, FoirFeedbackClient } from './FoirFeedback';
+export { createLocalStorageAdapter } from './localStorageAdapter';
+export type { FoirCustomer, SessionAdapter, AuthProviderPublic } from '../auth';
+export type { FoirEnv } from '../graphql/foir-request';

package/dist/react/localStorageAdapter.d.ts

@@ -0,0 +1,10 @@
+import type { SessionAdapter } from '../auth';
+/**
+ * A {@link SessionAdapter} backed by the browser's `localStorage`.
+ *
+ * SSR-safe: with no `window` (server render) reads return `null` and writes are
+ * no-ops, so {@link FoirProvider} starts in `loading` and hydrates the real
+ * session on the client after mount. This is the default adapter when you don't
+ * pass one to `FoirProvider`.
+ */
+export declare function createLocalStorageAdapter(): SessionAdapter;