@foir/sdk 0.7.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/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

@@ -1,10 +1,14 @@
 /**
- * `@foir/sdk/react` — a drop-in React auth layer for Foir customers.
+ * `@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';
@@ -14,6 +18,8 @@ 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';