@supacloud/js 0.21.1 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,6 +9,7 @@ It does **not** replace [`@supabase/supabase-js`](https://www.npmjs.com/package/
9
9
  - cancel / retry helpers
10
10
  - Realtime subscription with polling fallback
11
11
  - Supabase Queues helpers backed by the official `pgmq_public` RPC API, plus SupaCloud management extensions for queue administration and diagnostics
12
+ - Service-role-only durable workflow helpers backed by PostgreSQL and PGMQ
12
13
  - project OAuth/OIDC migration and OAuth client management
13
14
  - SupAuth provisioning and runtime verification helpers
14
15
 
@@ -284,6 +285,42 @@ Queue settings:
284
285
 
285
286
  Management extension conflicts are surfaced as `SupaCloudApiError` with `status`, `code`, and `responseBody`, so callers do not need to parse raw `fetch` responses.
286
287
 
288
+ ## Durable Workflows
289
+
290
+ `supacloud.workflows` coordinates code-defined, linear steps on the project's PostgreSQL and PGMQ runtime. Every workflow RPC is restricted to `service_role`; create this client only in a trusted worker or server process.
291
+
292
+ ```ts
293
+ const runId = crypto.randomUUID();
294
+
295
+ await supacloud.workflows.start({
296
+ runId,
297
+ workflowName: "invoice.issue",
298
+ workflowVersion: "1",
299
+ firstStepKey: "validate",
300
+ input: { invoiceId: "inv-123" },
301
+ });
302
+
303
+ const claim = await supacloud.workflows.claim({
304
+ workerId: "invoice-worker-1",
305
+ visibilityTimeoutSeconds: 300,
306
+ });
307
+
308
+ if (claim?.status === "claimed") {
309
+ await supacloud.workflows.complete({
310
+ stepId: claim.stepId,
311
+ messageId: claim.messageId,
312
+ attempt: claim.attempt,
313
+ workerId: claim.workerId,
314
+ stepOutput: { validated: true },
315
+ runOutput: { invoiceId: "inv-123" },
316
+ });
317
+ }
318
+ ```
319
+
320
+ Available operations are `start`, `claim`, `advance`, `complete`, `retry`, `fail`, `cancel`, `get`, and `events`. Mutating calls are safe to replay with the same request after a lost response; a different replay payload fails with an idempotency conflict. See the repository's `docs/durable-workflows.md` for execution, security, and DBOS design boundaries.
321
+
322
+ Message IDs, queue message IDs, event cursors, and run row versions are decimal strings, preserving the full PostgreSQL `bigint` range. Retry a `claim` that returns SQLSTATE `40001`; the contended queue lease is rolled back before that error is returned.
323
+
287
324
  ## OAuth/OIDC Helpers
288
325
 
289
326
  `client.auth.oauthServer` is the SupaCloud SDK surface for project-scoped OAuth 2.1 / OIDC migration and discovery.
package/dist/index.d.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  import type { SupabaseClient } from "@supabase/supabase-js";
2
+ import { SupaCloudWorkflowsClient } from "./workflows.js";
2
3
  export { createSupaCloudOAuthFetch, type SupaCloudOAuthFetchOptions, } from "./auth-fetch.js";
4
+ export * from "./workflows.js";
3
5
  export type SupaCloudTaskStatus = "pending" | "leased" | "running" | "retry_scheduled" | "succeeded" | "failed" | "dead_lettered" | "cancelled" | "queued" | "processing" | "completed";
4
6
  export type SupaCloudTaskLogEntry = {
5
7
  timestamp: string;
@@ -445,6 +447,7 @@ export declare function createSupaCloudClient<TClient extends SupabaseClient = S
445
447
  oauthClients: SupaCloudOAuthClientsClient<TClient>;
446
448
  };
447
449
  tasks: SupaCloudTasksClient<TClient>;
450
+ workflows: SupaCloudWorkflowsClient<TClient>;
448
451
  supauth: SupaCloudSupAuthClient<TClient>;
449
452
  queues: SupaCloudQueuesClient<TClient>;
450
453
  queue: (name: string) => SupaCloudQueueClient<TClient>;
package/dist/index.js CHANGED
@@ -1,3 +1,45 @@
1
+ // src/workflows.ts
2
+ class SupaCloudWorkflowsClient {
3
+ supabase;
4
+ constructor(supabase) {
5
+ this.supabase = supabase;
6
+ }
7
+ async invoke(functionName, request) {
8
+ const rpcClient = this.supabase;
9
+ const { data: rpcResponse, error: rpcError } = await rpcClient.rpc(functionName, { request });
10
+ if (rpcError)
11
+ throw rpcError;
12
+ return rpcResponse;
13
+ }
14
+ start(request) {
15
+ return this.invoke("supacloud_workflow_start", request);
16
+ }
17
+ claim(request) {
18
+ return this.invoke("supacloud_workflow_claim", request);
19
+ }
20
+ advance(request) {
21
+ return this.invoke("supacloud_workflow_advance", request);
22
+ }
23
+ complete(request) {
24
+ return this.invoke("supacloud_workflow_complete", request);
25
+ }
26
+ retry(request) {
27
+ return this.invoke("supacloud_workflow_retry", request);
28
+ }
29
+ fail(request) {
30
+ return this.invoke("supacloud_workflow_fail", request);
31
+ }
32
+ cancel(runId, reason) {
33
+ return this.invoke("supacloud_workflow_cancel", { runId, reason });
34
+ }
35
+ get(runId) {
36
+ return this.invoke("supacloud_workflow_get", { runId });
37
+ }
38
+ events(runId, options = {}) {
39
+ return this.invoke("supacloud_workflow_events", { runId, ...options });
40
+ }
41
+ }
42
+
1
43
  // src/auth-fetch.ts
2
44
  function requestMethod(input, init) {
3
45
  return (init?.method || (input instanceof Request ? input.method : "GET")).toUpperCase();
@@ -731,6 +773,7 @@ function createSupaCloudClient(options) {
731
773
  const oauthClients = new SupaCloudOAuthClientsClient(normalized);
732
774
  const supauth = new SupaCloudSupAuthClient(normalized);
733
775
  const queues = new SupaCloudQueuesClient(normalized);
776
+ const workflows2 = new SupaCloudWorkflowsClient(options.supabase);
734
777
  return {
735
778
  supabase: options.supabase,
736
779
  projectRef: normalized.projectRef,
@@ -740,6 +783,7 @@ function createSupaCloudClient(options) {
740
783
  oauthClients
741
784
  },
742
785
  tasks,
786
+ workflows: workflows2,
743
787
  supauth,
744
788
  queues,
745
789
  queue: (name) => new SupaCloudQueueClient(normalized, name),
@@ -751,6 +795,7 @@ function createSupaCloudClient(options) {
751
795
  export {
752
796
  createSupaCloudOAuthFetch,
753
797
  createSupaCloudClient,
798
+ SupaCloudWorkflowsClient,
754
799
  SupaCloudTaskSubmitError,
755
800
  SupaCloudApiError
756
801
  };
@@ -0,0 +1,133 @@
1
+ import type { SupabaseClient } from "@supabase/supabase-js";
2
+ export type SupaCloudWorkflowRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
3
+ export type SupaCloudWorkflowStepStatus = "queued" | "running" | "completed" | "failed" | "dead_lettered" | "cancelled";
4
+ export type SupaCloudWorkflowJson = Record<string, unknown>;
5
+ export interface SupaCloudWorkflowStep {
6
+ stepId: string;
7
+ stepKey: string;
8
+ status: SupaCloudWorkflowStepStatus;
9
+ input: SupaCloudWorkflowJson;
10
+ output: SupaCloudWorkflowJson;
11
+ errorMessage: string;
12
+ attempts: number;
13
+ maxAttempts: number;
14
+ retryDelaySeconds: number;
15
+ queueMessageId: string;
16
+ claimedBy: string | null;
17
+ claimedAt: string | null;
18
+ completedAt: string | null;
19
+ nextStepKey: string | null;
20
+ createdAt: string;
21
+ updatedAt: string;
22
+ }
23
+ export interface SupaCloudWorkflowRun {
24
+ runId: string;
25
+ workflowName: string;
26
+ workflowVersion: string;
27
+ status: SupaCloudWorkflowRunStatus;
28
+ input: SupaCloudWorkflowJson;
29
+ output: SupaCloudWorkflowJson;
30
+ errorMessage: string;
31
+ rowVersion: string;
32
+ createdAt: string;
33
+ startedAt: string | null;
34
+ completedAt: string | null;
35
+ updatedAt: string;
36
+ idempotent: boolean;
37
+ steps: SupaCloudWorkflowStep[];
38
+ }
39
+ export interface SupaCloudWorkflowStartRequest {
40
+ runId: string;
41
+ workflowName: string;
42
+ workflowVersion: string;
43
+ firstStepKey: string;
44
+ input?: SupaCloudWorkflowJson;
45
+ maxAttempts?: number;
46
+ }
47
+ export interface SupaCloudWorkflowClaimRequest {
48
+ workerId: string;
49
+ visibilityTimeoutSeconds?: number;
50
+ }
51
+ export interface SupaCloudWorkflowClaim {
52
+ status: "claimed";
53
+ runId: string;
54
+ workflowName: string;
55
+ workflowVersion: string;
56
+ stepId: string;
57
+ stepKey: string;
58
+ input: SupaCloudWorkflowJson;
59
+ messageId: string;
60
+ attempt: number;
61
+ maxAttempts: number;
62
+ workerId: string;
63
+ }
64
+ export interface SupaCloudWorkflowDeadLetter {
65
+ status: "dead_lettered";
66
+ runId: string;
67
+ stepId: string;
68
+ stepKey: string;
69
+ messageId: string;
70
+ attempt: number;
71
+ maxAttempts: number;
72
+ }
73
+ export interface SupaCloudWorkflowDiscardedMessage {
74
+ status: "discarded";
75
+ reason: "invalid_message" | "orphaned_message" | "step_not_claimable" | string;
76
+ messageId: string;
77
+ runId?: string;
78
+ stepId?: string;
79
+ }
80
+ export type SupaCloudWorkflowClaimResult = SupaCloudWorkflowClaim | SupaCloudWorkflowDeadLetter | SupaCloudWorkflowDiscardedMessage | null;
81
+ export interface SupaCloudWorkflowAttemptRequest {
82
+ stepId: string;
83
+ messageId: string;
84
+ attempt: number;
85
+ workerId: string;
86
+ }
87
+ export interface SupaCloudWorkflowAdvanceRequest extends SupaCloudWorkflowAttemptRequest {
88
+ output?: SupaCloudWorkflowJson;
89
+ nextStepKey: string;
90
+ nextInput?: SupaCloudWorkflowJson;
91
+ nextMaxAttempts?: number;
92
+ }
93
+ export interface SupaCloudWorkflowCompleteRequest extends SupaCloudWorkflowAttemptRequest {
94
+ stepOutput?: SupaCloudWorkflowJson;
95
+ runOutput?: SupaCloudWorkflowJson;
96
+ }
97
+ export interface SupaCloudWorkflowRetryRequest extends SupaCloudWorkflowAttemptRequest {
98
+ errorMessage: string;
99
+ delaySeconds?: number;
100
+ }
101
+ export interface SupaCloudWorkflowFailRequest extends SupaCloudWorkflowAttemptRequest {
102
+ errorMessage: string;
103
+ }
104
+ export interface SupaCloudWorkflowEvent {
105
+ eventId: string;
106
+ runId: string;
107
+ stepId: string | null;
108
+ eventType: string;
109
+ attempt: number | null;
110
+ details: SupaCloudWorkflowJson;
111
+ createdAt: string;
112
+ }
113
+ /**
114
+ * Service-role-only durable workflow RPC client. Constructed by
115
+ * `createSupaCloudClient`; never expose a service-role key in browser code.
116
+ */
117
+ export declare class SupaCloudWorkflowsClient<TClient extends SupabaseClient = SupabaseClient> {
118
+ private readonly supabase;
119
+ constructor(supabase: TClient);
120
+ private invoke;
121
+ start(request: SupaCloudWorkflowStartRequest): Promise<SupaCloudWorkflowRun>;
122
+ claim(request: SupaCloudWorkflowClaimRequest): Promise<SupaCloudWorkflowClaimResult>;
123
+ advance(request: SupaCloudWorkflowAdvanceRequest): Promise<SupaCloudWorkflowRun>;
124
+ complete(request: SupaCloudWorkflowCompleteRequest): Promise<SupaCloudWorkflowRun>;
125
+ retry(request: SupaCloudWorkflowRetryRequest): Promise<SupaCloudWorkflowRun>;
126
+ fail(request: SupaCloudWorkflowFailRequest): Promise<SupaCloudWorkflowRun>;
127
+ cancel(runId: string, reason: string): Promise<SupaCloudWorkflowRun>;
128
+ get(runId: string): Promise<SupaCloudWorkflowRun | null>;
129
+ events(runId: string, options?: {
130
+ afterEventId?: string;
131
+ limit?: number;
132
+ }): Promise<SupaCloudWorkflowEvent[]>;
133
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@supacloud/js",
3
- "version": "0.21.1",
3
+ "version": "0.22.0",
4
4
  "description": "Platform SDK for SupaCloud, built on top of supabase-js",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -45,7 +45,7 @@
45
45
  },
46
46
  "devDependencies": {
47
47
  "@types/bun": "^1.3.14",
48
- "@supabase/supabase-js": "^2.110.9",
48
+ "@supabase/supabase-js": "^2.112.2",
49
49
  "typescript": "^7.0.2"
50
50
  }
51
51
  }