@trigger.dev/react-hooks 0.0.0-chat-prerelease-20260401205942

package/dist/esm/hooks/useApiClient.js

@@ -0,0 +1,41 @@
+"use client";
+import { ApiClient } from "@trigger.dev/core/v3";
+import { useTriggerAuthContextOptional } from "../contexts.js";
+/**
+ * Hook to create an API client instance using authentication context or provided options.
+ *
+ * @param {UseApiClientOptions} [options] - Configuration options for the API client
+ * @returns {ApiClient} An initialized API client instance
+ * @throws {Error} When no access token is available in either context or options
+ *
+ * @example
+ * ```ts
+ * // Using context authentication
+ * const apiClient = useApiClient();
+ *
+ * // Using custom options
+ * const apiClient = useApiClient({
+ *   accessToken: "your-access-token",
+ *   baseURL: "https://api.my-trigger.com",
+ *   requestOptions: { retry: { maxAttempts: 10 } }
+ * });
+ * ```
+ */
+export function useApiClient(options) {
+    const auth = useTriggerAuthContextOptional();
+    const baseUrl = options?.baseURL ?? auth?.baseURL ?? "https://api.trigger.dev";
+    const accessToken = options?.accessToken ?? auth?.accessToken;
+    const previewBranch = options?.previewBranch ?? auth?.previewBranch;
+    if (!accessToken) {
+        if (options?.enabled === false) {
+            return undefined;
+        }
+        throw new Error("Missing accessToken in TriggerAuthContext or useApiClient options");
+    }
+    const requestOptions = {
+        ...auth?.requestOptions,
+        ...options?.requestOptions,
+    };
+    return new ApiClient(baseUrl, accessToken, previewBranch, requestOptions);
+}
+//# sourceMappingURL=useApiClient.js.map

package/dist/esm/hooks/useApiClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useApiClient.js","sourceRoot":"","sources":["../../../src/hooks/useApiClient.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAqB,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAuB/D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,OAA6B;IACxD,MAAM,IAAI,GAAG,6BAA6B,EAAE,CAAC;IAE7C,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,OAAO,IAAI,yBAAyB,CAAC;IAC/E,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,WAAW,CAAC;IAC9D,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,IAAI,EAAE,aAAa,CAAC;IACpE,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,IAAI,OAAO,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;YAC/B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,cAAc,GAAsB;QACxC,GAAG,IAAI,EAAE,cAAc;QACvB,GAAG,OAAO,EAAE,cAAc;KAC3B,CAAC;IAEF,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC;AAC5E,CAAC"}

package/dist/esm/hooks/useInputStreamSend.d.ts

@@ -0,0 +1,26 @@
+import { UseApiClientOptions } from "./useApiClient.js";
+export interface InputStreamSendInstance<TData> {
+    /** Send data to the input stream */
+    send: (data: TData) => void;
+    /** Whether a send is currently in progress */
+    isLoading: boolean;
+    /** Any error that occurred during the last send */
+    error?: Error;
+    /** Whether the hook is ready to send (has runId and access token) */
+    isReady: boolean;
+}
+/**
+ * Hook to send data to an input stream on a running task.
+ *
+ * @template TData - The type of data to send
+ * @param streamId - The input stream identifier
+ * @param runId - The run to send input stream data to
+ * @param options - API client options (e.g. accessToken)
+ *
+ * @example
+ * ```tsx
+ * const { send, isLoading } = useInputStreamSend("my-stream", runId, { accessToken });
+ * send({ message: "hello" });
+ * ```
+ */
+export declare function useInputStreamSend<TData>(streamId: string, runId?: string, options?: UseApiClientOptions): InputStreamSendInstance<TData>;

package/dist/esm/hooks/useInputStreamSend.js

@@ -0,0 +1,39 @@
+"use client";
+import useSWRMutation from "swr/mutation";
+import { useApiClient } from "./useApiClient.js";
+/**
+ * Hook to send data to an input stream on a running task.
+ *
+ * @template TData - The type of data to send
+ * @param streamId - The input stream identifier
+ * @param runId - The run to send input stream data to
+ * @param options - API client options (e.g. accessToken)
+ *
+ * @example
+ * ```tsx
+ * const { send, isLoading } = useInputStreamSend("my-stream", runId, { accessToken });
+ * send({ message: "hello" });
+ * ```
+ */
+export function useInputStreamSend(streamId, runId, options) {
+    const apiClient = useApiClient(options);
+    async function sendToStream(key, { arg }) {
+        if (!apiClient) {
+            throw new Error("Could not send to input stream: Missing access token");
+        }
+        if (!runId) {
+            throw new Error("Could not send to input stream: Missing run ID");
+        }
+        return await apiClient.sendInputStream(runId, streamId, arg.data);
+    }
+    const mutation = useSWRMutation(runId ? `input-stream:${runId}:${streamId}` : null, sendToStream);
+    return {
+        send: (data) => {
+            mutation.trigger({ data });
+        },
+        isLoading: mutation.isMutating,
+        isReady: !!runId && !!apiClient,
+        error: mutation.error,
+    };
+}
+//# sourceMappingURL=useInputStreamSend.js.map

package/dist/esm/hooks/useInputStreamSend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInputStreamSend.js","sourceRoot":"","sources":["../../../src/hooks/useInputStreamSend.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,cAAc,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAuB,MAAM,mBAAmB,CAAC;AAatE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,KAAc,EACd,OAA6B;IAE7B,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAExC,KAAK,UAAU,YAAY,CAAC,GAAW,EAAE,EAAE,GAAG,EAA4B;QACxE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QAED,OAAO,MAAM,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,KAAK,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAElG,OAAO;QACL,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;YACb,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7B,CAAC;QACD,SAAS,EAAE,QAAQ,CAAC,UAAU;QAC9B,OAAO,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,SAAS;QAC/B,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC"}

package/dist/esm/hooks/useRealtime.d.ts

@@ -0,0 +1,294 @@
+import { AnyTask, InferStreamType, RealtimeDefinedStream, RealtimeRun, RealtimeRunSkipColumns } from "@trigger.dev/core/v3";
+import { UseApiClientOptions } from "./useApiClient.js";
+export type UseRealtimeRunOptions = UseApiClientOptions & {
+    id?: string;
+    enabled?: boolean;
+    /**
+     * The number of milliseconds to throttle the stream updates.
+     *
+     * @default 16
+     */
+    throttleInMs?: number;
+};
+export type UseRealtimeSingleRunOptions<TTask extends AnyTask = AnyTask> = UseRealtimeRunOptions & {
+    /**
+     * Callback this is called when the run completes, an error occurs, or the subscription is stopped.
+     *
+     * @param {RealtimeRun<TTask>} run - The run object
+     * @param {Error} [err] - The error that occurred
+     */
+    onComplete?: (run: RealtimeRun<TTask>, err?: Error) => void;
+    /**
+     * Whether to stop the subscription when the run completes
+     *
+     * @default true
+     *
+     * Set this to false if you are making updates to the run metadata after completion through child runs
+     */
+    stopOnCompletion?: boolean;
+    /**
+     * Skip columns from the subscription.
+     *
+     * @default []
+     */
+    skipColumns?: RealtimeRunSkipColumns;
+};
+export type UseRealtimeRunInstance<TTask extends AnyTask = AnyTask> = {
+    run: RealtimeRun<TTask> | undefined;
+    error: Error | undefined;
+    /**
+     * Abort the current request immediately.
+     */
+    stop: () => void;
+};
+/**
+ * Hook to subscribe to realtime updates of a task run.
+ *
+ * @template TTask - The type of the task
+ * @param {string} [runId] - The unique identifier of the run to subscribe to
+ * @param {UseRealtimeSingleRunOptions} [options] - Configuration options for the subscription
+ * @returns {UseRealtimeRunInstance<TTask>} An object containing the current state of the run, error handling, and control methods
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { run, error } = useRealtimeRun<typeof myTask>('run-id-123');
+ * ```
+ */
+export declare function useRealtimeRun<TTask extends AnyTask>(runId?: string, options?: UseRealtimeSingleRunOptions<TTask>): UseRealtimeRunInstance<TTask>;
+export type StreamResults<TStreams extends Record<string, any>> = {
+    [K in keyof TStreams]: Array<TStreams[K]>;
+};
+export type UseRealtimeRunWithStreamsInstance<TTask extends AnyTask = AnyTask, TStreams extends Record<string, any> = Record<string, any>> = {
+    run: RealtimeRun<TTask> | undefined;
+    streams: StreamResults<TStreams>;
+    error: Error | undefined;
+    /**
+     * Abort the current request immediately, keep the generated tokens if any.
+     */
+    stop: () => void;
+};
+/**
+ * Hook to subscribe to realtime updates of a task run with associated data streams.
+ *
+ * @template TTask - The type of the task
+ * @template TStreams - The type of the streams data
+ * @param {string} [runId] - The unique identifier of the run to subscribe to
+ * @param {UseRealtimeRunOptions} [options] - Configuration options for the subscription
+ * @returns {UseRealtimeRunWithStreamsInstance<TTask, TStreams>} An object containing the current state of the run, streams data, and error handling
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { run, streams, error } = useRealtimeRunWithStreams<typeof myTask, {
+ *   output: string;
+ * }>('run-id-123');
+ * ```
+ */
+export declare function useRealtimeRunWithStreams<TTask extends AnyTask = AnyTask, TStreams extends Record<string, any> = Record<string, any>>(runId?: string, options?: UseRealtimeSingleRunOptions<TTask>): UseRealtimeRunWithStreamsInstance<TTask, TStreams>;
+export type UseRealtimeRunsInstance<TTask extends AnyTask = AnyTask> = {
+    runs: RealtimeRun<TTask>[];
+    error: Error | undefined;
+    /**
+     * Abort the current request immediately.
+     */
+    stop: () => void;
+};
+export type UseRealtimeRunsWithTagOptions = UseRealtimeRunOptions & {
+    /**
+     * Filter runs by the time they were created. You must specify the duration string like "1h", "10s", "30m", etc.
+     *
+     * @example
+     * "1h" - 1 hour ago
+     * "10s" - 10 seconds ago
+     * "30m" - 30 minutes ago
+     * "1d" - 1 day ago
+     * "1w" - 1 week ago
+     *
+     * The maximum duration is 1 week
+     *
+     * @note The timestamp will be calculated on the server side when you first subscribe to the runs.
+     *
+     */
+    createdAt?: string;
+    /**
+     * Skip columns from the subscription.
+     *
+     * @default []
+     */
+    skipColumns?: RealtimeRunSkipColumns;
+};
+/**
+ * Hook to subscribe to realtime updates of task runs filtered by tag(s).
+ *
+ * @template TTask - The type of the task
+ * @param {string | string[]} tag - The tag or array of tags to filter runs by
+ * @param {UseRealtimeRunOptions} [options] - Configuration options for the subscription
+ * @returns {UseRealtimeRunsInstance<TTask>} An object containing the current state of the runs and any error encountered
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { runs, error } = useRealtimeRunsWithTag<typeof myTask>('my-tag');
+ * // Or with multiple tags
+ * const { runs, error } = useRealtimeRunsWithTag<typeof myTask>(['tag1', 'tag2']);
+ * // Or with a createdAt filter
+ * const { runs, error } = useRealtimeRunsWithTag<typeof myTask>('my-tag', { createdAt: '1h' });
+ * ```
+ */
+export declare function useRealtimeRunsWithTag<TTask extends AnyTask>(tag: string | string[], options?: UseRealtimeRunsWithTagOptions): UseRealtimeRunsInstance<TTask>;
+/**
+ * Hook to subscribe to realtime updates of a batch of task runs.
+ *
+ * @template TTask - The type of the task
+ * @param {string} batchId - The unique identifier of the batch to subscribe to
+ * @param {UseRealtimeRunOptions} [options] - Configuration options for the subscription
+ * @returns {UseRealtimeRunsInstance<TTask>} An object containing the current state of the runs, error handling, and control methods
+ *
+ * @example
+ * ```ts
+ * import type { myTask } from './path/to/task';
+ * const { runs, error } = useRealtimeBatch<typeof myTask>('batch-id-123');
+ * ```
+ */
+export declare function useRealtimeBatch<TTask extends AnyTask>(batchId: string, options?: UseRealtimeRunOptions): UseRealtimeRunsInstance<TTask>;
+export type UseRealtimeStreamInstance<TPart> = {
+    parts: Array<TPart>;
+    error: Error | undefined;
+    /**
+     * Abort the current request immediately, keep the generated tokens if any.
+     */
+    stop: () => void;
+};
+export type UseRealtimeStreamOptions<TPart> = UseApiClientOptions & {
+    id?: string;
+    enabled?: boolean;
+    /**
+     * The number of milliseconds to throttle the stream updates.
+     *
+     * @default 16
+     */
+    throttleInMs?: number;
+    /**
+     * The number of seconds to wait for new data to be available,
+     * If no data arrives within the timeout, the stream will be closed.
+     *
+     * @default 60 seconds
+     */
+    timeoutInSeconds?: number;
+    /**
+     * The index to start reading from.
+     * If not provided, the stream will start from the beginning.
+     * @default 0
+     */
+    startIndex?: number;
+    /**
+     * Callback this is called when new data is received.
+     */
+    onData?: (data: TPart) => void;
+};
+export declare function useRealtimeStream<TDefinedStream extends RealtimeDefinedStream<any>>(stream: TDefinedStream, runId: string, options?: UseRealtimeStreamOptions<InferStreamType<TDefinedStream>>): UseRealtimeStreamInstance<InferStreamType<TDefinedStream>>;
+/**
+ * Hook to subscribe to realtime updates of a stream with a specific stream key.
+ *
+ * This hook automatically subscribes to a stream and updates the `parts` array as new data arrives.
+ * The stream subscription is automatically managed: it starts when the component mounts (or when
+ * `enabled` becomes `true`) and stops when the component unmounts or when `stop()` is called.
+ *
+ * @template TPart - The type of each chunk/part in the stream
+ * @param runId - The unique identifier of the run to subscribe to
+ * @param streamKey - The unique identifier of the stream to subscribe to. Use this overload
+ *   when you want to read from a specific stream key.
+ * @param options - Optional configuration for the stream subscription
+ * @returns An object containing:
+ *   - `parts`: An array of all stream chunks received so far (accumulates over time)
+ *   - `error`: Any error that occurred during subscription
+ *   - `stop`: A function to manually stop the subscription
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useRealtimeStream } from "@trigger.dev/react-hooks";
+ *
+ * function StreamViewer({ runId }: { runId: string }) {
+ *   const { parts, error } = useRealtimeStream<string>(
+ *     runId,
+ *     "my-stream",
+ *     {
+ *       accessToken: process.env.NEXT_PUBLIC_TRIGGER_PUBLIC_KEY,
+ *     }
+ *   );
+ *
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   // Parts array accumulates all chunks
+ *   const fullText = parts.join("");
+ *
+ *   return <div>{fullText}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom options
+ * const { parts, error, stop } = useRealtimeStream<ChatChunk>(
+ *   runId,
+ *   "chat-stream",
+ *   {
+ *     accessToken: publicKey,
+ *     timeoutInSeconds: 120,
+ *     startIndex: 10, // Start from the 10th chunk
+ *     throttleInMs: 50, // Throttle updates to every 50ms
+ *     onData: (chunk) => {
+ *       console.log("New chunk received:", chunk);
+ *     },
+ *   }
+ * );
+ *
+ * // Manually stop the subscription
+ * <button onClick={stop}>Stop Stream</button>
+ * ```
+ */
+export declare function useRealtimeStream<TPart>(runId: string, streamKey: string, options?: UseRealtimeStreamOptions<TPart>): UseRealtimeStreamInstance<TPart>;
+/**
+ * Hook to subscribe to realtime updates of a stream using the default stream key (`"default"`).
+ *
+ * This is a convenience overload that allows you to subscribe to the default stream without
+ * specifying a stream key. The stream will be accessed with the key `"default"`.
+ *
+ * @template TPart - The type of each chunk/part in the stream
+ * @param runId - The unique identifier of the run to subscribe to
+ * @param options - Optional configuration for the stream subscription
+ * @returns An object containing:
+ *   - `parts`: An array of all stream chunks received so far (accumulates over time)
+ *   - `error`: Any error that occurred during subscription
+ *   - `stop`: A function to manually stop the subscription
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useRealtimeStream } from "@trigger.dev/react-hooks";
+ *
+ * function DefaultStreamViewer({ runId }: { runId: string }) {
+ *   // Subscribe to the default stream
+ *   const { parts, error } = useRealtimeStream<string>(runId, {
+ *     accessToken: process.env.NEXT_PUBLIC_TRIGGER_PUBLIC_KEY,
+ *   });
+ *
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   const fullText = parts.join("");
+ *   return <div>{fullText}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Conditionally enable the stream
+ * const { parts } = useRealtimeStream<string>(runId, {
+ *   accessToken: publicKey,
+ *   enabled: !!runId && isStreaming, // Only subscribe when runId exists and isStreaming is true
+ * });
+ * ```
+ */
+export declare function useRealtimeStream<TPart>(runId: string, options?: UseRealtimeStreamOptions<TPart>): UseRealtimeStreamInstance<TPart>;