@workflow/web-shared 4.0.1-beta.5

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @workflow/web-shared
+
+Workflow Observability tools for NextJS. See [Workflow DevKit](https://useworkflow.dev/docs/observability) for more information.
+
+## Usage
+
+This package contains client and server code to interact with the Workflow API, as well as some pre-styled components.
+If you want to deploy a full observability experience with your NextJS app, take a look at [`@workflow/web`](../web/README.md) instead, which can be self-hosted.
+
+You can use the API to create your own display UI, like so:
+
+```tsx
+import { useWorkflowRuns } from '@workflow/web-shared';
+
+export default function MyRunsList() {
+  const {
+    data,
+    error,
+    nextPage,
+    previousPage,
+    hasNextPage,
+    hasPreviousPage,
+    reload,
+    pageInfo,
+  } = useWorkflowRuns(env, {
+    sortOrder,
+    workflowName: workflowNameFilter === 'all' ? undefined : workflowNameFilter,
+    status: status === 'all' ? undefined : status,
+  });
+
+  // Shows an interactive trace viewer for the given run
+  return <div>{runs.map((run) => (
+    <div key={run.runId}>
+      {run.workflowName}
+      {run.status}
+      {run.startedAt}
+      {run.completedAt}
+    </div>
+  ))}</div>;
+}
+```
+
+It also comes with a pre-styled interactive trace viewer that you can use to display the trace for a given run:
+
+```tsx
+import { RunTraceView } from '@workflow/web-shared';
+
+export default function MyRunDetailView({ env, runId }: { env: EnvMap, runId: string }) {
+  // ... your other code
+
+  // Shows an interactive trace viewer for the given run
+  return <RunTraceView env={env} runId={runId} />;
+}
+```
+
+## Environment Variables
+
+For API calls to work, you'll need to pass the same environment variables that are used by the Workflow CLI.
+See `npx workflow inspect --help` for more information.
+
+If you're deploying this as part of your Vercel NextJS app, setting `WORKFLOW_TARGET_WORLD` to `vercel` is enough
+to infer your other project details from the Vercel environment variables.
+
+## Styling
+
+In order for tailwind classes to be picked up correctly, you might need to configure your NextJS app
+to use the correct CSS processor. E.g. if you're using PostCSS with TailwindCSS, you can do the following:
+
+```tsx
+// postcss.config.mjs in your NextJS app
+const config = {
+  plugins: ['@tailwindcss/postcss'],
+};
+
+export default config;
+```

package/dist/api/workflow-api-client.d.ts

@@ -0,0 +1,303 @@
+import type { Hook, WorkflowRun, WorkflowRunStatus } from '@workflow/world';
+import type { EnvMap } from './workflow-server-actions';
+/**
+ * Gets a user-facing error message from an error object.
+ * Handles both WorkflowAPIError and regular Error instances.
+ */
+export declare const getErrorMessage: (error: Error | WorkflowAPIError) => string;
+/**
+ *  Error instance for API and server-side errors.
+ * `error.message` will be a user-facing error message, to be displayed in UI.
+ * `error.cause` will be a developer-facing error message, to be displayed in logs.
+ *
+ *  If the error originates from an HTTP request made from a server action,
+ *  these fields will be populated:
+ *  - `error.request` will be a JSON-serializable object representing the request made.
+ *  - `error.layer` will be 'API'
+ *
+ *  If the error originates from inside the server action, or there's an error with
+ *  calling the server action, these fields will be populated:
+ *  - `error.layer` will be 'server'
+ */
+export declare class WorkflowAPIError extends Error {
+    request?: any;
+    layer?: 'client' | 'server' | 'API';
+    constructor(message: string, options?: {
+        cause?: unknown;
+        request?: any;
+        layer?: 'client' | 'server' | 'API';
+    });
+}
+interface PageResult<T> {
+    data: T[] | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+interface PaginatedList<T> {
+    data: PageResult<T>;
+    allData: PageResult<T>[];
+    error: Error | null;
+    isLoading: boolean;
+    currentPage: number;
+    totalPages: number;
+    nextPage: () => void;
+    previousPage: () => void;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    reload: () => void;
+    pageInfo: string;
+}
+/**
+ * Returns a list of runs with pagination control
+ */
+export declare function useWorkflowRuns(env: EnvMap, params: {
+    workflowName?: string;
+    status?: WorkflowRunStatus;
+    limit?: number;
+    sortOrder?: 'asc' | 'desc';
+}): PaginatedList<WorkflowRun>;
+/**
+ * Returns a list of hooks with pagination control
+ */
+export declare function useWorkflowHooks(env: EnvMap, params: {
+    runId?: string;
+    limit?: number;
+    sortOrder?: 'asc' | 'desc';
+}): PaginatedList<Hook>;
+/**
+ * Returns (and keeps up-to-date) all data related to a run.
+ * Items returned will _not_ have resolved data (like input/output values).
+ */
+export declare function useWorkflowTraceViewerData(env: EnvMap, runId: string, options?: {
+    live?: boolean;
+}): {
+    run: {
+        runId: string;
+        deploymentId: string;
+        status: "pending" | "running" | "completed" | "failed" | "paused" | "cancelled";
+        workflowName: string;
+        input: any[];
+        createdAt: Date;
+        updatedAt: Date;
+        executionContext?: Record<string, any> | undefined;
+        output?: any;
+        error?: string | undefined;
+        errorCode?: string | undefined;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+    };
+    steps: {
+        runId: string;
+        stepId: string;
+        stepName: string;
+        status: "pending" | "running" | "completed" | "failed" | "cancelled";
+        input: any[];
+        attempt: number;
+        createdAt: Date;
+        updatedAt: Date;
+        output?: any;
+        error?: string | undefined;
+        errorCode?: string | undefined;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        retryAfter?: Date | undefined;
+    }[];
+    hooks: {
+        runId: string;
+        hookId: string;
+        token: string;
+        ownerId: string;
+        projectId: string;
+        environment: string;
+        createdAt: Date;
+        metadata?: unknown;
+    }[];
+    events: (({
+        eventType: "step_completed";
+        correlationId: string;
+        eventData: {
+            result: any;
+        };
+    } | {
+        eventType: "step_failed";
+        correlationId: string;
+        eventData: {
+            error: any;
+            stack?: string | undefined;
+            fatal?: boolean | undefined;
+        };
+    } | {
+        eventType: "step_retrying";
+        correlationId: string;
+        eventData: {
+            attempt: number;
+        };
+    } | {
+        eventType: "step_started";
+        correlationId: string;
+    } | {
+        eventType: "hook_created";
+        correlationId: string;
+    } | {
+        eventType: "hook_received";
+        correlationId: string;
+        eventData: {
+            payload: any;
+        };
+    } | {
+        eventType: "hook_disposed";
+        correlationId: string;
+    } | {
+        eventType: "wait_created";
+        correlationId: string;
+        eventData: {
+            resumeAt: Date;
+        };
+    } | {
+        eventType: "wait_completed";
+        correlationId: string;
+    } | {
+        eventType: "workflow_completed";
+        correlationId?: string | undefined;
+    } | {
+        eventType: "workflow_failed";
+        eventData: {
+            error: any;
+        };
+        correlationId?: string | undefined;
+    } | {
+        eventType: "workflow_started";
+        correlationId?: string | undefined;
+    }) & {
+        runId: string;
+        eventId: string;
+        createdAt: Date;
+    })[];
+    loading: boolean;
+    error: Error | null;
+    update: () => Promise<{
+        foundNewItems: boolean;
+    }>;
+};
+/**
+ * Returns (and keeps up-to-date) data inherent to a specific run/step/hook,
+ * resolving input/output/metadata, AND loading all related events with full event data.
+ */
+export declare function useWorkflowResourceData(env: EnvMap, resource: 'run' | 'step' | 'hook' | 'sleep', resourceId: string, options?: {
+    refreshInterval?: number;
+    runId?: string;
+}): {
+    data: {
+        runId: string;
+        deploymentId: string;
+        status: "pending" | "running" | "completed" | "failed" | "paused" | "cancelled";
+        workflowName: string;
+        input: any[];
+        createdAt: Date;
+        updatedAt: Date;
+        executionContext?: Record<string, any> | undefined;
+        output?: any;
+        error?: string | undefined;
+        errorCode?: string | undefined;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+    } | {
+        runId: string;
+        stepId: string;
+        stepName: string;
+        status: "pending" | "running" | "completed" | "failed" | "cancelled";
+        input: any[];
+        attempt: number;
+        createdAt: Date;
+        updatedAt: Date;
+        output?: any;
+        error?: string | undefined;
+        errorCode?: string | undefined;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        retryAfter?: Date | undefined;
+    } | (({
+        eventType: "step_completed";
+        correlationId: string;
+        eventData: {
+            result: any;
+        };
+    } | {
+        eventType: "step_failed";
+        correlationId: string;
+        eventData: {
+            error: any;
+            stack?: string | undefined;
+            fatal?: boolean | undefined;
+        };
+    } | {
+        eventType: "step_retrying";
+        correlationId: string;
+        eventData: {
+            attempt: number;
+        };
+    } | {
+        eventType: "step_started";
+        correlationId: string;
+    } | {
+        eventType: "hook_created";
+        correlationId: string;
+    } | {
+        eventType: "hook_received";
+        correlationId: string;
+        eventData: {
+            payload: any;
+        };
+    } | {
+        eventType: "hook_disposed";
+        correlationId: string;
+    } | {
+        eventType: "wait_created";
+        correlationId: string;
+        eventData: {
+            resumeAt: Date;
+        };
+    } | {
+        eventType: "wait_completed";
+        correlationId: string;
+    } | {
+        eventType: "workflow_completed";
+        correlationId?: string | undefined;
+    } | {
+        eventType: "workflow_failed";
+        eventData: {
+            error: any;
+        };
+        correlationId?: string | undefined;
+    } | {
+        eventType: "workflow_started";
+        correlationId?: string | undefined;
+    }) & {
+        runId: string;
+        eventId: string;
+        createdAt: Date;
+    }) | {
+        runId: string;
+        hookId: string;
+        token: string;
+        ownerId: string;
+        projectId: string;
+        environment: string;
+        createdAt: Date;
+        metadata?: unknown;
+    } | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * Cancel a workflow run
+ */
+export declare function cancelRun(env: EnvMap, runId: string): Promise<void>;
+/**
+ * Start a new workflow run
+ */
+export declare function recreateRun(env: EnvMap, runId: string): Promise<string>;
+export declare function readStream(env: EnvMap, streamId: string, startIndex?: number): Promise<ReadableStream<Uint8Array>>;
+export {};
+//# sourceMappingURL=workflow-api-client.d.ts.map

package/dist/api/workflow-api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-api-client.d.ts","sourceRoot":"","sources":["../../src/api/workflow-api-client.ts"],"names":[],"mappings":"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"}