@postrun/react 0.2.0 → 1.0.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import * as react from 'react';
 import { ReactNode, CSSProperties } from 'react';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { QueryClient, QueryKey } from '@tanstack/react-query';
-import { PostrunClient, ListProfilesQuery, ConnectionKind, ConnectionStatus, ListMediaQuery, ListPostsQuery, ConnectablePlatform, MediaTarget, MediaKind, Metadata, MediaResource, ComposePostInput, XPostVariant, LinkedInPostVariant } from '@postrun/js';
+import { PostrunClient, ListProfilesQuery, DiscoverableAccountList, Connection, ConnectionKind, ConnectionStatus, ListMediaQuery, ListPostsQuery, ConnectablePlatform, MediaResource, MediaTarget, MediaKind, Metadata, ComposePostInput, XPostVariant, LinkedInPostVariant } from '@postrun/js';
 import { TwitterComponents } from 'react-tweet';
 
 /**
@@ -191,6 +191,45 @@ declare function useDeleteProfile(): _tanstack_react_query.UseMutationResult<{
     deleted: true;
 }, Error, string, unknown>;
 
+/**
+ * The pure orchestration behind the embedded (no-redirect) connect flow. It is
+ * the in-app twin of the hosted `/connect` runner's machine, sharing its exact
+ * shape — grant → correlate by the Nango `connectionId` → discover → pick →
+ * select — and its two invariants:
+ *
+ *   1. It NEVER throws: every path resolves to one typed `ConnectOutcome`, so the
+ *      hook can map it straight to a UI state and a seam can't crash a host app.
+ *   2. Correlation is EXACT: `nango.auth()` resolves with the Nango `connectionId`,
+ *      the SAME value the auth webhook stores as `nango_connection_id`. We poll the
+ *      connections list filtered by that id, so the row this grant produced is found
+ *      unambiguously — a concurrent connect on the same profile can't be mis-picked.
+ *
+ * All seams (the Nango grant, the host's account picker, the four API calls) are
+ * INJECTED, so the whole machine unit-tests without a DOM, a network, or a real
+ * `nango.auth()`. The hook (`useConnect`) wires the real seams onto it.
+ */
+/** One account offered for selection — the element type of the accounts list. */
+type DiscoverableAccount = DiscoverableAccountList['data'][number];
+/** Why a connect attempt ended in `error` — actionable reasons for the host. */
+type ConnectErrorReason = 'popup_blocked' | 'auth_failed' | 'connection_not_found' | 'select_failed' | 'reauth_required';
+/**
+ * The single outcome of a connect attempt. `active` carries the activated
+ * connection (so the host can call `onConnected`); `connected_pending` means the
+ * grant succeeded but no account is bound yet (slow webhook, out-of-band binding,
+ * or no reachable accounts) — the host refetches its list, it is NOT an error.
+ */
+type ConnectOutcome = {
+    status: 'active';
+    connection: Connection;
+} | {
+    status: 'connected_pending';
+} | {
+    status: 'cancelled';
+} | {
+    status: 'error';
+    reason: ConnectErrorReason;
+};
+
 /** The connection-list filter that keys the cache (social/ads + lifecycle). */
 interface ConnectionsFilter {
     kind?: ConnectionKind;
@@ -294,24 +333,71 @@ declare const connectionKeys: {
     accounts: (id: string) => readonly ["postrun", "connections", "accounts", string];
 };
 
-interface ConnectParams {
+interface UseConnectParams {
     /** The profile to attach the new connection to. */
     profileId: string;
     /** The platform to connect (X, LinkedIn, Meta, …). */
     platform: ConnectablePlatform;
+    /** Called once a connection is fully ACTIVE (an account is bound). */
+    onConnected?: (connection: Connection) => void;
 }
 /**
- * Start a connect flow: mint a session and redirect the browser to the hosted
- * connect URL on postrun.ai, where the full white-labeled OAuth journey runs and
- * the user is returned to the host app. Bare-bones by design — the OAuth UI is
- * ours and hosted, so the host app just calls `mutate({ profileId, platform })`.
- * On return, the new connection appears via `useConnections`.
+ * The connect flow's UI state. `connected_pending` is a TERMINAL success state —
+ * the grant landed but no account is bound yet (a slow webhook, an out-of-band
+ * binding, or no reachable accounts); the host shows "almost there" and refetches
+ * its connections list. It is NOT an error and must not hang in `connecting`.
  */
-declare function useConnect(): _tanstack_react_query.UseMutationResult<{
-    hosted_connect_url: string;
-    connect_token: string;
-    expires_at: string;
-}, Error, ConnectParams, unknown>;
+type ConnectState = {
+    phase: 'preparing';
+} | {
+    phase: 'idle';
+} | {
+    phase: 'connecting';
+} | {
+    phase: 'picking';
+    accounts: DiscoverableAccount[];
+} | {
+    phase: 'active';
+    connection: Connection;
+} | {
+    phase: 'connected_pending';
+} | {
+    phase: 'cancelled';
+} | {
+    phase: 'error';
+    reason: ConnectErrorReason;
+};
+interface UseConnectResult {
+    /** The current flow state — drive your button + picker + status off `phase`. */
+    state: ConnectState;
+    /**
+     * Start the OAuth flow. MUST be called directly in the user's click handler
+     * (no `await` before it): it opens the OAuth popup synchronously, so the
+     * browser keeps it inside the user gesture. A no-op until the session is ready
+     * (state `preparing`) — disable the button until `phase` is `idle`.
+     */
+    start: () => void;
+    /** When `phase` is `picking`, activate the connection with the chosen account. */
+    select: (externalAccountId: string) => void;
+    /** Return to a fresh, ready state (re-mints the session) — e.g. a "try again". */
+    reset: () => void;
+}
+/**
+ * Embedded one-click connect — the customer's OWN button drives the whole OAuth
+ * flow IN-APP (no redirect to our hosted page). `nango.auth()` opens a popup that
+ * resolves in-page, then the account picker (for multi-account platforms) renders
+ * inside the host app via `state.accounts` + `select()`. White-label, one click.
+ *
+ * The Plaid pattern: the Nango session is PRE-MINTED on mount (and on `reset`),
+ * because `nango.auth()` opens its popup synchronously — minting in the click
+ * would push `window.open` out of the user gesture and the browser would block
+ * the popup. `start()` therefore fires `nango.auth()` with the already-held token
+ * and zero `await` before it.
+ *
+ * The hosted `/connect` page remains the fallback for callers NOT using this SDK
+ * (a plain link to `hosted_connect_url`); this hook never redirects.
+ */
+declare function useConnect({ profileId, platform, onConnected, }: UseConnectParams): UseConnectResult;
 /**
  * List a profile's connected accounts. Pass a `filter` to narrow by `kind`
  * (`posting` = social, `ads`) or `status` — e.g. a composer fetches
@@ -404,15 +490,77 @@ declare function useDisconnect(): _tanstack_react_query.UseMutationResult<{
     deleted: true;
 }, Error, string, unknown>;
 
+/** The flow state + actions handed to your render-prop. */
+interface ConnectRenderApi {
+    /** The current flow state — switch on `state.phase` to render your UI. */
+    state: ConnectState;
+    /**
+     * Begin connecting. Call this DIRECTLY from your button's `onClick` — it opens
+     * the OAuth popup synchronously, so don't `await` anything before it. A no-op
+     * until the session is ready (`state.phase === 'preparing'`).
+     */
+    start: () => void;
+    /** When `state.phase === 'picking'`, activate with the chosen account id. */
+    select: (externalAccountId: string) => void;
+    /** Reset to a fresh, ready state (e.g. a "try again" after an error/cancel). */
+    reset: () => void;
+}
+interface ConnectProps {
+    /** The profile to attach the new connection to. */
+    profileId: string;
+    /** The platform to connect (X, LinkedIn, Meta, …). */
+    platform: ConnectablePlatform;
+    /** Called once a connection is fully ACTIVE (an account is bound). */
+    onConnected?: (connection: Connection) => void;
+    /** Render your own button + picker + status from the flow state. */
+    children: (api: ConnectRenderApi) => ReactNode;
+}
+/**
+ * Headless one-click connect. Wraps `useConnect` and hands you the flow state +
+ * actions via a render-prop, so you own EVERY pixel (your button, your account
+ * picker, your brand marks, your styling) while the SDK runs the embedded OAuth
+ * popup + account binding — no redirect, no second click.
+ *
+ * ```tsx
+ * <Connect profileId={id} platform="x" onConnected={refetch}>
+ *   {({ state, start, select }) =>
+ *     state.phase === 'picking' ? (
+ *       <ul>
+ *         {state.accounts.map((a) => (
+ *           <li key={a.external_account_id}>
+ *             <button onClick={() => select(a.external_account_id)}>
+ *               {a.name ?? a.external_account_id}
+ *             </button>
+ *           </li>
+ *         ))}
+ *       </ul>
+ *     ) : (
+ *       <button onClick={start} disabled={state.phase !== 'idle'}>
+ *         Connect X
+ *       </button>
+ *     )
+ *   }
+ * </Connect>
+ * ```
+ *
+ * The trigger MUST call `start()` directly in the click (it opens the popup
+ * synchronously). Mount `<Connect>` inside a `<PostrunProvider>`.
+ */
+declare function Connect({ profileId, platform, onConnected, children, }: ConnectProps): ReactNode;
+
 type MediaUploadStatus = 'idle' | 'uploading' | 'processing' | 'ready' | 'failed';
 interface MediaUploadOptions {
     /** Profile that owns the asset. */
     profileId: string;
     /** Platforms to validate + render for (omit to add later via useUpdateMedia). */
     targets?: MediaTarget[];
-    /** Override the kind inferred from the file's MIME. */
+    /** Optional override — omit and the API auto-detects the kind from the bytes. */
     kind?: MediaKind;
-    /** The file's MIME type. Defaults to `file.type`; required when that's empty. */
+    /**
+     * Optional override — omit and the API auto-detects the MIME from the bytes.
+     * Still useful for a legacy Office binary (.doc/.ppt) whose magic bytes can't be
+     * disambiguated by the server sniff.
+     */
     contentType?: string;
     /** Store as-is with zero processing. */
     raw?: boolean;
@@ -420,74 +568,60 @@ interface MediaUploadOptions {
     externalId?: string;
     metadata?: Metadata;
 }
-/**
- * Upload a file and get back a platform-validated asset. The hook owns the whole
- * journey: infer kind/content_type from the `File`, create the asset, PUT the
- * bytes with live `progress` + retry, poll until processing settles, and expose
- * `media.per_platform` (per-target status, url, warnings, errors). `cancel()`
- * aborts an in-flight upload.
- */
-declare function useMediaUpload(): {
-    upload: (file: File, options: MediaUploadOptions) => Promise<MediaResource>;
-    cancel: () => void | undefined;
-    reset: () => void;
-    status: MediaUploadStatus;
+/** One file's slot in an upload — its own live status, progress, and settled
+ *  asset. `status` is never `idle` (an item exists only once uploading). */
+interface MediaUploadItem {
+    /** Stable local id (NOT the asset id) — use as the React key and for `remove`. */
+    id: string;
+    file: File;
+    status: Exclude<MediaUploadStatus, 'idle'>;
+    /** 0–1 client-side BYTE-upload bar. `media.progress.{stage,percent}` is the
+     *  live SERVER pipeline bar. */
     progress: number;
-    media: {
-        id: string;
-        object: "media";
-        profile_id: string;
-        kind: "image" | "video" | "gif" | "document" | null;
-        content_type: string | null;
-        status: "uploading" | "processing" | "ready" | "failed";
-        raw: boolean;
-        error: {
-            code: "media_unprobeable" | "media_format_indeterminate" | "media_too_large" | "media_aspect_ratio_unsupported" | "media_resolution_too_low" | "media_gif_unsupported" | "media_format_recompressed" | "media_resolution_downscaled" | "video_container_unsupported" | "video_codec_unsupported" | "video_audio_codec_unsupported" | "video_too_large" | "video_too_small" | "video_dimensions_unsupported" | "video_dimensions_too_large" | "video_fps_unsupported" | "video_fps_too_low" | "video_aspect_unsupported" | "video_duration_too_short" | "video_duration_exceeds_max" | "video_transform_failed" | "media_fetch_failed" | "document_format_unsupported" | "document_too_large" | "document_too_many_pages" | "media_unsupported";
-            message: string;
-            hint?: string;
-            allowed?: Array<string>;
-            got?: string;
-        } | null;
-        source: {
-            format: string;
-            bytes: number;
-            width: number | null;
-            height: number | null;
-            duration_ms: number | null;
-        } | null;
-        alt_text: string | null;
-        per_platform: {
-            [key: string]: {
-                status: "processing" | "ready" | "failed";
-                url: string | null;
-                width: number | null;
-                height: number | null;
-                bytes: number | null;
-                warnings: Array<{
-                    code: "media_unprobeable" | "media_format_indeterminate" | "media_too_large" | "media_aspect_ratio_unsupported" | "media_resolution_too_low" | "media_gif_unsupported" | "media_format_recompressed" | "media_resolution_downscaled" | "video_container_unsupported" | "video_codec_unsupported" | "video_audio_codec_unsupported" | "video_too_large" | "video_too_small" | "video_dimensions_unsupported" | "video_dimensions_too_large" | "video_fps_unsupported" | "video_fps_too_low" | "video_aspect_unsupported" | "video_duration_too_short" | "video_duration_exceeds_max" | "video_transform_failed" | "media_fetch_failed" | "document_format_unsupported" | "document_too_large" | "document_too_many_pages" | "media_unsupported";
-                    message: string;
-                    hint?: string;
-                    allowed?: Array<string>;
-                    got?: string;
-                }>;
-                errors: Array<{
-                    code: "media_unprobeable" | "media_format_indeterminate" | "media_too_large" | "media_aspect_ratio_unsupported" | "media_resolution_too_low" | "media_gif_unsupported" | "media_format_recompressed" | "media_resolution_downscaled" | "video_container_unsupported" | "video_codec_unsupported" | "video_audio_codec_unsupported" | "video_too_large" | "video_too_small" | "video_dimensions_unsupported" | "video_dimensions_too_large" | "video_fps_unsupported" | "video_fps_too_low" | "video_aspect_unsupported" | "video_duration_too_short" | "video_duration_exceeds_max" | "video_transform_failed" | "media_fetch_failed" | "document_format_unsupported" | "document_too_large" | "document_too_many_pages" | "media_unsupported";
-                    message: string;
-                    hint?: string;
-                    allowed?: Array<string>;
-                    got?: string;
-                }>;
-            };
-        };
-        external_id: string | null;
-        metadata: {
-            [key: string]: string | number | boolean;
-        };
-        created_at: string;
-        updated_at: string;
-    } | null;
+    media: MediaResource | null;
     error: unknown;
-};
+}
+interface UseMediaUploadResult {
+    /** Every file added, in add-order, with its live state. */
+    items: readonly MediaUploadItem[];
+    /** The settled-ready assets, in item order — what you attach to a post. */
+    ready: readonly MediaResource[];
+    /** True while any item is still uploading or processing. */
+    isUploading: boolean;
+    /**
+     * Upload ONE file or MANY under `options`, gated by `concurrency`. The reactive
+     * `items` update live for UI; the returned promise is for imperative flows —
+     * it resolves to the settled (`ready`|`failed`) resources for THIS batch, in
+     * add-order, EXCLUDING any item removed/aborted mid-flight. Single-file usage:
+     * `const [asset] = await add(file, opts)`.
+     */
+    add: (files: File | FileList | readonly File[], options: MediaUploadOptions) => Promise<MediaResource[]>;
+    /** Drop an item by local id — aborts it if still in flight. */
+    remove: (id: string) => void;
+    /** Abort everything and clear the list. */
+    reset: () => void;
+}
+interface UseMediaUploadOptions {
+    /**
+     * How many files upload at once; the rest queue (default 3). Fixed for the
+     * hook's lifetime — set it once when you call the hook.
+     */
+    concurrency?: number;
+}
+/**
+ * Upload one OR many files and get back platform-validated assets. The hook owns
+ * the whole journey per file: create the asset (the API auto-detects
+ * kind/content_type from the bytes), PUT the bytes with live `progress` + retry,
+ * poll until processing settles, and expose `media.per_platform` (per-target
+ * status, url, warnings,
+ * errors). Every file gets its own `MediaUploadItem` slot in `items`; `ready` is
+ * the settled assets to attach to a post; `remove`/`reset` abort in-flight work.
+ * Uploads run through ONE shared `p-limit` gate so only `concurrency` (default 3)
+ * are in flight at once — global across `add` calls, not per-call.
+ *
+ * Single-file usage: `const [asset] = await add(file, opts)` (or read `ready[0]`).
+ */
+declare function useMediaUpload(options?: UseMediaUploadOptions): UseMediaUploadResult;
 /** Retrieve a media asset; auto-polls while it is still uploading/processing. */
 declare function useMedia(id: string): _tanstack_react_query.UseQueryResult<NoInfer<{
     id: string;
@@ -496,6 +630,10 @@ declare function useMedia(id: string): _tanstack_react_query.UseQueryResult<NoIn
     kind: "image" | "video" | "gif" | "document" | null;
     content_type: string | null;
     status: "uploading" | "processing" | "ready" | "failed";
+    progress: {
+        stage: "queued" | "analyzing" | "transcoding" | "done";
+        percent: number;
+    };
     raw: boolean;
     error: {
         code: "media_unprobeable" | "media_format_indeterminate" | "media_too_large" | "media_aspect_ratio_unsupported" | "media_resolution_too_low" | "media_gif_unsupported" | "media_format_recompressed" | "media_resolution_downscaled" | "video_container_unsupported" | "video_codec_unsupported" | "video_audio_codec_unsupported" | "video_too_large" | "video_too_small" | "video_dimensions_unsupported" | "video_dimensions_too_large" | "video_fps_unsupported" | "video_fps_too_low" | "video_aspect_unsupported" | "video_duration_too_short" | "video_duration_exceeds_max" | "video_transform_failed" | "media_fetch_failed" | "document_format_unsupported" | "document_too_large" | "document_too_many_pages" | "media_unsupported";
@@ -557,6 +695,10 @@ declare function useMediaList(query?: ListMediaQuery): _tanstack_react_query.Use
         kind: "image" | "video" | "gif" | "document" | null;
         content_type: string | null;
         status: "uploading" | "processing" | "ready" | "failed";
+        progress: {
+            stage: "queued" | "analyzing" | "transcoding" | "done";
+            percent: number;
+        };
         raw: boolean;
         error: {
             code: "media_unprobeable" | "media_format_indeterminate" | "media_too_large" | "media_aspect_ratio_unsupported" | "media_resolution_too_low" | "media_gif_unsupported" | "media_format_recompressed" | "media_resolution_downscaled" | "video_container_unsupported" | "video_codec_unsupported" | "video_audio_codec_unsupported" | "video_too_large" | "video_too_small" | "video_dimensions_unsupported" | "video_dimensions_too_large" | "video_fps_unsupported" | "video_fps_too_low" | "video_aspect_unsupported" | "video_duration_too_short" | "video_duration_exceeds_max" | "video_transform_failed" | "media_fetch_failed" | "document_format_unsupported" | "document_too_large" | "document_too_many_pages" | "media_unsupported";
@@ -622,6 +764,10 @@ declare function useMediaInfinite(filters?: Omit<ListMediaQuery, 'limit' | 'offs
     kind: "image" | "video" | "gif" | "document" | null;
     content_type: string | null;
     status: "uploading" | "processing" | "ready" | "failed";
+    progress: {
+        stage: "queued" | "analyzing" | "transcoding" | "done";
+        percent: number;
+    };
     raw: boolean;
     error: {
         code: "media_unprobeable" | "media_format_indeterminate" | "media_too_large" | "media_aspect_ratio_unsupported" | "media_resolution_too_low" | "media_gif_unsupported" | "media_format_recompressed" | "media_resolution_downscaled" | "video_container_unsupported" | "video_codec_unsupported" | "video_audio_codec_unsupported" | "video_too_large" | "video_too_small" | "video_dimensions_unsupported" | "video_dimensions_too_large" | "video_fps_unsupported" | "video_fps_too_low" | "video_aspect_unsupported" | "video_duration_too_short" | "video_duration_exceeds_max" | "video_transform_failed" | "media_fetch_failed" | "document_format_unsupported" | "document_too_large" | "document_too_many_pages" | "media_unsupported";
@@ -676,6 +822,10 @@ declare function useUpdateMedia(): _tanstack_react_query.UseMutationResult<{
     kind: "image" | "video" | "gif" | "document" | null;
     content_type: string | null;
     status: "uploading" | "processing" | "ready" | "failed";
+    progress: {
+        stage: "queued" | "analyzing" | "transcoding" | "done";
+        percent: number;
+    };
     raw: boolean;
     error: {
         code: "media_unprobeable" | "media_format_indeterminate" | "media_too_large" | "media_aspect_ratio_unsupported" | "media_resolution_too_low" | "media_gif_unsupported" | "media_format_recompressed" | "media_resolution_downscaled" | "video_container_unsupported" | "video_codec_unsupported" | "video_audio_codec_unsupported" | "video_too_large" | "video_too_small" | "video_dimensions_unsupported" | "video_dimensions_too_large" | "video_fps_unsupported" | "video_fps_too_low" | "video_aspect_unsupported" | "video_duration_too_short" | "video_duration_exceeds_max" | "video_transform_failed" | "media_fetch_failed" | "document_format_unsupported" | "document_too_large" | "document_too_many_pages" | "media_unsupported";
@@ -1089,7 +1239,7 @@ declare function useCreatePost(profileId: string): {
     } | undefined;
     reset: () => void;
     isReady: boolean;
-    connectedChannels: ("x" | "linkedin" | "facebook_page" | "tiktok" | "instagram")[];
+    connectedChannels: ("x" | "linkedin" | "facebook_page" | "instagram" | "tiktok")[];
 };
 /**
  * Update a post by id. Pass a light edit directly (`{ schedule_at }`,
@@ -1443,4 +1593,4 @@ declare function LinkedInPostPreviewImpl({ variant, author, media, theme, time,
  * absorbs unstable media arrays). */
 declare const LinkedInPostPreview: react.MemoExoticComponent<typeof LinkedInPostPreviewImpl>;
 
-export { type CalendarFilters, type ConnectParams, type ConnectionsFilter, type InfiniteList, LinkedInPostPreview, type LinkedInPostPreviewProps, type LinkedInPreviewAuthor, type LiveOptions, type MediaUploadOptions, type MediaUploadStatus, type PostrunContextValue, PostrunProvider, type PostrunProviderProps, type PreviewMedia, type PreviewMediaKind, UploadError, XPostPreview, type XPostPreviewProps, type XPreviewAuthor, type XPreviewMedia, type XPreviewQuotedTweet, connectionKeys, mediaKeys, postKeys, profileKeys, useCalendar, useConnect, useConnection, useConnections, useCreatePost, useCreateProfile, useDeleteMedia, useDeletePost, useDeleteProfile, useDisconnect, useDiscoverableAccounts, useInfiniteList, useMedia, useMediaInfinite, useMediaList, useMediaUpload, usePost, usePostrun, usePosts, usePostsInfinite, useProfile, useProfiles, useProfilesInfinite, useSelectAccount, useUpdateMedia, useUpdatePost, useUpdateProfile };
+export { type CalendarFilters, Connect, type ConnectErrorReason, type ConnectOutcome, type ConnectProps, type ConnectRenderApi, type ConnectState, type ConnectionsFilter, type DiscoverableAccount, type InfiniteList, LinkedInPostPreview, type LinkedInPostPreviewProps, type LinkedInPreviewAuthor, type LiveOptions, type MediaUploadItem, type MediaUploadOptions, type MediaUploadStatus, type PostrunContextValue, PostrunProvider, type PostrunProviderProps, type PreviewMedia, type PreviewMediaKind, UploadError, type UseConnectParams, type UseConnectResult, type UseMediaUploadOptions, type UseMediaUploadResult, XPostPreview, type XPostPreviewProps, type XPreviewAuthor, type XPreviewMedia, type XPreviewQuotedTweet, connectionKeys, mediaKeys, postKeys, profileKeys, useCalendar, useConnect, useConnection, useConnections, useCreatePost, useCreateProfile, useDeleteMedia, useDeletePost, useDeleteProfile, useDisconnect, useDiscoverableAccounts, useInfiniteList, useMedia, useMediaInfinite, useMediaList, useMediaUpload, usePost, usePostrun, usePosts, usePostsInfinite, useProfile, useProfiles, useProfilesInfinite, useSelectAccount, useUpdateMedia, useUpdatePost, useUpdateProfile };