@supacloud/js 0.21.2 → 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 +37 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +45 -0
- package/dist/workflows.d.ts +133 -0
- package/package.json +1 -1
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
|
+
}
|