@syndew/oluso-sdk 0.0.0-stage → 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,559 @@
+import React, { ReactNode } from 'react';
+
+/**
+ * SDK Configuration
+ */
+interface OlusoConfig {
+    /**
+     * Base URL of the Oluso server
+     * @example "https://auth.oluso.io"
+     */
+    serverUrl: string;
+    /**
+     * Tenant identifier (subdomain or ID). Leave it out when the server URL is the tenant's own host, or when your
+     * `fetch` already names the tenant.
+     * @example "acme" or "tenant_abc123"
+     */
+    tenant?: string;
+    /**
+     * Optional public API key for rate limiting/analytics
+     * Not used for authentication - journeys handle their own auth
+     */
+    apiKey?: string;
+    /**
+     * Custom fetch implementation (for SSR or testing)
+     */
+    fetch?: typeof fetch;
+    /**
+     * Extra headers for each request, e.g. the signed-in user's access token (and DPoP proof) for a session your
+     * own backend started for that user. Called per request with its method and URL.
+     */
+    headers?: (request: {
+        method: string;
+        url: string;
+    }) => Record<string, string> | Promise<Record<string, string>>;
+}
+/**
+ * Field definition from a journey policy
+ */
+interface JourneyField {
+    name: string;
+    type: 'text' | 'email' | 'password' | 'number' | 'date' | 'tel' | 'url' | 'textarea' | 'select' | 'radio' | 'checkbox';
+    label: string;
+    placeholder?: string;
+    description?: string;
+    required: boolean;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    validation?: {
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+        min?: number;
+        max?: number;
+    };
+}
+/**
+ * Journey metadata returned from the API
+ */
+interface JourneyInfo {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    fields: JourneyField[];
+    ui?: {
+        title?: string;
+        logoUrl?: string;
+        primaryColor?: string;
+        backgroundColor?: string;
+    };
+    requiresAuthentication: boolean;
+}
+/**
+ * Submission result
+ */
+interface SubmissionResult {
+    success: boolean;
+    submissionId?: string;
+    message?: string;
+    redirectUrl?: string;
+    errors?: Record<string, string>;
+}
+/**
+ * A journey running step by step through the headless API (start, step, session).
+ * Every headless call returns the session as it stands after the call.
+ */
+interface JourneySession {
+    sessionId: string;
+    /** The journey's slug */
+    slug: string;
+    status: 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired';
+    success: boolean;
+    completed: boolean;
+    /** The step waiting for input, while in progress */
+    currentStep?: string;
+    /** Same as currentStep: set while there is a step to complete */
+    nextStep?: string;
+    completedSteps: string[];
+    expiresAt?: string;
+    /** What to render for the current step */
+    step?: JourneyStepView;
+    /** The step continues elsewhere (e.g. an external identity provider) */
+    redirectUrl?: string;
+    /** Authentication journeys: the authorization code to redeem with the PKCE verifier */
+    code?: string;
+    /** Data-collection journeys: the success message once completed */
+    message?: string;
+    error?: string;
+    errorDescription?: string;
+}
+/** A step to render: its definition and the model the server renders it from */
+interface JourneyStepView {
+    id: string;
+    /** Step type, e.g. local_login, mfa, dynamic_form */
+    type: string;
+    displayName?: string;
+    /** The server view the step renders as */
+    view?: string;
+    /** Fields, options, messages and errors for the step */
+    model?: Record<string, unknown>;
+    /** The step as a form any client can draw (see JourneyStepForm) */
+    form?: JourneyStepForm;
+    /** The hosted view's markup, for a step that has no form description (custom pages, plugin views) */
+    html?: string;
+    actions: JourneyStepAction[];
+}
+/**
+ * A step as a form. Posting its fields with the clicked action's name and value is exactly what the hosted page
+ * posts, so any journey step can be drawn by any client.
+ */
+interface JourneyStepForm {
+    title?: string;
+    description?: string;
+    /** What went wrong with the last submission */
+    error?: string;
+    /** Something to tell the person that isn't an error */
+    notice?: string;
+    fields: JourneyFormField[];
+    /** The buttons, in order; each posts the fields with its own name and value */
+    actions: JourneyFormAction[];
+    links: JourneyFormLink[];
+    /** Browser work for the step: passkey, captcha, QR code, recovery codes or waiting */
+    widget?: JourneyFormWidget;
+}
+type JourneyFormFieldType = 'text' | 'email' | 'password' | 'number' | 'date' | 'tel' | 'url' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'file' | 'hidden' | 'otp' | 'content';
+interface JourneyFormField {
+    name: string;
+    type: JourneyFormFieldType | string;
+    label?: string;
+    placeholder?: string;
+    description?: string;
+    /** Guidance under the input, e.g. upload limits */
+    hint?: string;
+    required: boolean;
+    readOnly: boolean;
+    value?: string;
+    error?: string;
+    options?: JourneyFormOption[];
+    pattern?: string;
+    patternError?: string;
+    minLength?: number;
+    maxLength?: number;
+    min?: string;
+    max?: string;
+    rows?: number;
+    autocomplete?: string;
+    autofocus: boolean;
+    accept?: string;
+    maxFiles?: number;
+    maxFileSizeMb?: number;
+    capture?: string;
+    /** Phone: countries to pick from; the country is posted as `${name}__country` */
+    countries?: JourneyFormCountry[];
+    country?: string;
+    showWhen?: JourneyFormCondition;
+    /** Shown only while every one of these is met too */
+    showWhenAll?: JourneyFormCondition[];
+    group?: string;
+}
+interface JourneyFormOption {
+    value: string;
+    label: string;
+    description?: string;
+    disabled: boolean;
+}
+interface JourneyFormCountry {
+    code: string;
+    name: string;
+    dialCode: string;
+    flag?: string;
+}
+interface JourneyFormCondition {
+    field: string;
+    operator: string;
+    value?: string;
+}
+interface JourneyFormAction {
+    /** The posted name; absent for a button that posts no name of its own */
+    name?: string;
+    value?: string;
+    label: string;
+    /** Text shown with the button, e.g. "Didn't get the code?" before a resend link */
+    description?: string;
+    /** A question to confirm before the button posts; the renderer asks inline */
+    confirm?: string;
+    /** More values the button posts */
+    values?: Record<string, string>;
+    /** False: the button posts only its own name, value and values, none of the step's fields */
+    postsFields: boolean;
+    kind: 'primary' | 'secondary' | 'link' | 'cancel' | string;
+    skipValidation: boolean;
+}
+interface JourneyFormLink {
+    label: string;
+    url: string;
+}
+interface JourneyFormWidget {
+    type: 'webauthn_get' | 'webauthn_create' | 'captcha' | 'qr' | 'codes' | 'poll' | string;
+    data?: Record<string, unknown>;
+    /** Where the widget's result is posted */
+    resultField?: string;
+    /** The action posted with the result */
+    submit?: JourneyFormAction;
+}
+interface JourneyStepAction {
+    id: string;
+    label: string;
+    isPrimary: boolean;
+    isCancel: boolean;
+}
+/** The session after a step was submitted */
+type StepResult = JourneySession;
+/**
+ * Event types emitted by the SDK
+ */
+type OlusoEventType = 'journey:started' | 'journey:step' | 'journey:completed' | 'journey:error' | 'submission:success' | 'submission:error' | 'auth:success' | 'auth:error';
+interface OlusoEvent {
+    type: OlusoEventType;
+    /** The journey's slug */
+    slug: string;
+    /** The headless session, for journey events */
+    sessionId?: string;
+    data?: unknown;
+    error?: Error;
+}
+type OlusoEventListener = (event: OlusoEvent) => void;
+
+/**
+ * Oluso SDK Client
+ *
+ * @example
+ * ```typescript
+ * const oluso = new OlusoClient({
+ *   serverUrl: 'https://auth.oluso.io',
+ *   tenant: 'acme',
+ * });
+ *
+ * // Get journey info (form fields, etc.)
+ * const journey = await oluso.getJourney('waitlist');
+ *
+ * // Submit data
+ * const result = await oluso.submit('waitlist', {
+ *   email: 'user@example.com',
+ *   name: 'John Doe',
+ * });
+ * ```
+ */
+declare class OlusoClient {
+    private config;
+    private fetchFn;
+    private listeners;
+    constructor(config: OlusoConfig);
+    /**
+     * Get journey information including form fields. Journeys are named by slug.
+     */
+    getJourney(slug: string): Promise<JourneyInfo>;
+    /**
+     * Submit data to a data collection journey (waitlist, contact, survey, etc.)
+     */
+    submit(slug: string, data: Record<string, unknown>, options?: {
+        /** Client-side metadata */
+        metadata?: Record<string, string>;
+        /** Honeypot field for spam detection */
+        honeypot?: string;
+    }): Promise<SubmissionResult>;
+    /**
+     * Start a multi-step journey and run its first step. Without data the session's `step`
+     * is the first step to render; with data, that is the first step's input.
+     */
+    startJourney(slug: string, data?: Record<string, unknown>): Promise<JourneySession>;
+    /**
+     * Start a sign-in (or any authentication) journey for a public client. When the session completes it carries an
+     * authorization code, redeemed at the token endpoint with the PKCE verifier and redirect_uri "postmessage". Use
+     * this when your app keeps its own tokens; OlusoAuth.mountSignIn does the whole round trip for you.
+     */
+    startAuthJourney(slug: string, auth: {
+        clientId: string;
+        codeChallenge: string;
+        scope?: string;
+    }, data?: Record<string, unknown>): Promise<JourneySession>;
+    /**
+     * Submit input (or an action such as "resend") for the session's current step.
+     * The result is the session afterwards: the next step to render, or the completion.
+     */
+    submitStep(sessionId: string, data?: Record<string, unknown>, action?: string): Promise<StepResult>;
+    /**
+     * Submit the current step the way a form posts it: every field, files under their field's name, and the
+     * clicked button's name and value. Use this for steps with file fields; `action` is a step action such as "init".
+     */
+    submitStepForm(sessionId: string, form: FormData, action?: string): Promise<StepResult>;
+    /** The server this client talks to */
+    get serverUrl(): string;
+    /**
+     * Get where a multi-step session stands (status, current step), without running it
+     */
+    getSession(sessionId: string): Promise<JourneySession>;
+    /**
+     * URL of the hosted journey page (/journey/start/{slug}) to redirect to
+     */
+    getJourneyUrl(slug: string, options?: {
+        redirectUri?: string;
+        state?: string;
+    }): string;
+    /**
+     * URL of the hosted journey page (/journey/start/{slug}) for an iframe
+     */
+    getEmbedUrl(slug: string, options?: {
+        theme?: 'light' | 'dark';
+        hideHeader?: boolean;
+    }): string;
+    /**
+     * Subscribe to SDK events
+     */
+    on(event: OlusoEventType | '*', listener: OlusoEventListener): () => void;
+    /**
+     * Unsubscribe from SDK events
+     */
+    off(event: OlusoEventType | '*', listener: OlusoEventListener): void;
+    private emit;
+    private request;
+}
+/**
+ * Custom error class for SDK errors
+ */
+declare class OlusoError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly fieldErrors?: Record<string, string> | undefined;
+    constructor(message: string, status: number, code?: string | undefined, fieldErrors?: Record<string, string> | undefined);
+}
+
+/** Text the renderer shows itself; everything about a step comes from the server in the person's language. */
+interface JourneyLabels {
+    loading: string;
+    completed: string;
+    failed: string;
+    expired: string;
+    restart: string;
+    takePhoto: string;
+    copy: string;
+    copied: string;
+    passkey: string;
+    retry: string;
+    waiting: string;
+    unavailable: string;
+}
+
+interface OlusoProviderProps {
+    config: OlusoConfig;
+    children: ReactNode;
+}
+/**
+ * Provider component for Oluso SDK
+ *
+ * @example
+ * ```tsx
+ * <OlusoProvider config={{ serverUrl: 'https://auth.yoursite.com', tenant: 'acme' }}>
+ *   <App />
+ * </OlusoProvider>
+ * ```
+ */
+declare function OlusoProvider({ config, children }: OlusoProviderProps): React.JSX.Element;
+/**
+ * Hook to access the Oluso client
+ */
+declare function useOluso(): OlusoClient;
+interface UseJourneyOptions {
+    /** The journey's slug (as in /journey/start/{slug}) */
+    slug: string;
+    /** Callback on successful submission */
+    onSuccess?: (result: SubmissionResult) => void;
+    /** Callback on error */
+    onError?: (error: OlusoError) => void;
+    /** Initial form values */
+    defaultValues?: Record<string, unknown>;
+}
+interface UseJourneyResult {
+    /** Journey metadata and field definitions */
+    journey: JourneyInfo | null;
+    /** Loading state for initial fetch */
+    isLoading: boolean;
+    /** Submitting state */
+    isSubmitting: boolean;
+    /** Error from fetch or submission */
+    error: OlusoError | null;
+    /** Current form values */
+    values: Record<string, unknown>;
+    /** Field-level errors */
+    fieldErrors: Record<string, string>;
+    /** Update a field value */
+    setValue: (field: string, value: unknown) => void;
+    /** Submit the form */
+    submit: () => Promise<SubmissionResult | null>;
+    /** Reset the form */
+    reset: () => void;
+}
+/**
+ * Hook for working with a journey (headless)
+ *
+ * @example
+ * ```tsx
+ * function WaitlistForm() {
+ *   const { journey, values, setValue, submit, isSubmitting, fieldErrors } = useJourney({
+ *     slug: 'waitlist',
+ *     onSuccess: () => alert('Thanks for signing up!'),
+ *   });
+ *
+ *   if (!journey) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <form onSubmit={(e) => { e.preventDefault(); submit(); }}>
+ *       {journey.fields.map((field) => (
+ *         <div key={field.name}>
+ *           <label>{field.label}</label>
+ *           <input
+ *             type={field.type}
+ *             value={values[field.name] as string || ''}
+ *             onChange={(e) => setValue(field.name, e.target.value)}
+ *           />
+ *           {fieldErrors[field.name] && <span>{fieldErrors[field.name]}</span>}
+ *         </div>
+ *       ))}
+ *       <button type="submit" disabled={isSubmitting}>
+ *         {isSubmitting ? 'Submitting...' : 'Submit'}
+ *       </button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+declare function useJourney(options: UseJourneyOptions): UseJourneyResult;
+interface JourneyFormProps {
+    /** The journey's slug (as in /journey/start/{slug}) */
+    slug: string;
+    /** Callback on successful submission */
+    onSuccess?: (result: SubmissionResult) => void;
+    /** Callback on error */
+    onError?: (error: OlusoError) => void;
+    /** Custom class name */
+    className?: string;
+    /** Custom submit button text */
+    submitText?: string;
+    /** Custom loading text */
+    loadingText?: string;
+    /** Render custom field */
+    renderField?: (field: JourneyField, props: FieldRenderProps) => ReactNode;
+    /** Render custom submit button */
+    renderSubmit?: (props: {
+        isSubmitting: boolean;
+        onClick: () => void;
+    }) => ReactNode;
+    /** Show success message instead of form after submission */
+    showSuccessMessage?: boolean;
+    /** Custom success message component */
+    renderSuccess?: (result: SubmissionResult) => ReactNode;
+}
+interface FieldRenderProps {
+    value: unknown;
+    onChange: (value: unknown) => void;
+    error?: string;
+}
+/**
+ * Pre-built form component that renders a journey form
+ *
+ * @example
+ * ```tsx
+ * <JourneyForm
+ *   slug="waitlist"
+ *   onSuccess={() => console.log('Submitted!')}
+ *   submitText="Join Waitlist"
+ * />
+ * ```
+ */
+declare function JourneyForm({ slug, onSuccess, onError, className, submitText, loadingText, renderField, renderSubmit, showSuccessMessage, renderSuccess, }: JourneyFormProps): React.JSX.Element;
+interface JourneyProps {
+    /** Start this journey by slug (a waitlist, a contact form, a survey, a sign-up) */
+    slug?: string;
+    /** Input for the first step */
+    data?: Record<string, unknown>;
+    /** Continue a session your backend started, e.g. for the signed-in user */
+    session?: JourneySession;
+    /** Start the session yourself, e.g. a sign-in journey with PKCE */
+    start?: () => Promise<JourneySession>;
+    onStep?: (session: JourneySession) => void;
+    onComplete?: (session: JourneySession) => void | Promise<void>;
+    onError?: (error: Error, session?: JourneySession) => void;
+    onRedirect?: (url: string, session: JourneySession) => void;
+    showCompletion?: boolean;
+    theme?: 'light' | 'dark' | 'auto';
+    unstyled?: boolean;
+    labels?: Partial<JourneyLabels>;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Render any journey in place and run it step by step: forms with uploads, sign-in with MFA or passkeys,
+ * verification codes, consent. Uses the client from OlusoProvider.
+ *
+ * @example
+ * ```tsx
+ * <Journey slug="contact-us" onComplete={() => setSent(true)} />
+ * ```
+ */
+declare function Journey({ className, style, ...options }: JourneyProps): React.JSX.Element;
+interface JourneyEmbedProps {
+    /** The journey's slug (as in /journey/start/{slug}) */
+    slug: string;
+    /** Width of the iframe */
+    width?: string | number;
+    /** Height of the iframe */
+    height?: string | number;
+    /** Theme */
+    theme?: 'light' | 'dark';
+    /** Hide the header */
+    hideHeader?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Custom style */
+    style?: React.CSSProperties;
+    /** Callback when journey completes (via postMessage) */
+    onComplete?: (result: SubmissionResult) => void;
+}
+/**
+ * Embed a journey via iframe
+ *
+ * @example
+ * ```tsx
+ * <JourneyEmbed
+ *   slug="waitlist"
+ *   height={400}
+ *   onComplete={(result) => console.log('Submitted!', result)}
+ * />
+ * ```
+ */
+declare function JourneyEmbed({ slug, width, height, theme, hideHeader, className, style, onComplete, }: JourneyEmbedProps): React.JSX.Element;
+
+export { type FieldRenderProps, Journey, JourneyEmbed, type JourneyEmbedProps, JourneyForm, type JourneyFormProps, type JourneyProps, OlusoProvider, type OlusoProviderProps, type UseJourneyOptions, type UseJourneyResult, useJourney, useOluso };