@supacloud/js 0.16.0 → 0.17.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
@@ -10,6 +10,7 @@ It does **not** replace [`@supabase/supabase-js`](https://www.npmjs.com/package/
10
10
  - Realtime subscription with polling fallback
11
11
  - queue send / receive / ack / release / fail / retry / delete / list / listFailed / stats / settings helpers
12
12
  - project OAuth/OIDC migration and OAuth client management
13
+ - SupAuth provisioning and runtime verification helpers
13
14
 
14
15
  ## Install
15
16
 
@@ -34,12 +35,63 @@ const supacloud = createSupaCloudClient({
34
35
  const task = await supacloud.tasks.submit("aorist-ai/generate/crop", {
35
36
  body: { image_id: "img_123" },
36
37
  idempotencyKey: "crop-img_123-v1",
38
+ correlationId: "workflow-run-123",
39
+ businessTaskId: "aorist-task-123",
40
+ metadata: {
41
+ workflow_id: "workflow-123",
42
+ billing_subject: "user-123",
43
+ },
37
44
  });
38
45
 
39
46
  const finalState = await task.wait();
40
47
  console.log(finalState.status);
41
48
  ```
42
49
 
50
+ ## SupAuth Management
51
+
52
+ `supacloud.supauth` is a management-plane helper for provisioning and verifying a SupAuth/SupaOAuth runtime on SupaCloud. It is intended for trusted server-side tools, CI jobs, or admin backends that can call the SupaCloud Management API.
53
+
54
+ ```ts
55
+ const supacloud = createSupaCloudClient({
56
+ supabase,
57
+ managementApiUrl: "https://admin.example.com",
58
+ projectRef: "abcd1234",
59
+ getAccessToken: () => process.env.SUPACLOUD_MANAGEMENT_TOKEN ?? null,
60
+ });
61
+
62
+ await supacloud.supauth.provision({
63
+ authDomain: "auth.example.com",
64
+ apiDomain: "api.example.com",
65
+ adminMode: "sso",
66
+ storageBuckets: [{ id: "avatars", public: true }],
67
+ });
68
+
69
+ await supacloud.supauth.reconcile({ dryRun: false });
70
+
71
+ const health = await supacloud.supauth.verify();
72
+ if (!health.healthy) {
73
+ throw new Error("SupAuth runtime is not healthy");
74
+ }
75
+
76
+ const config = await supacloud.supauth.getClientConfig();
77
+ console.log(config.authUrl);
78
+ ```
79
+
80
+ The helper maps to these SupaCloud Management API routes:
81
+
82
+ - `POST /v1/projects/:projectRef/supauth/provision`
83
+ - `POST /v1/projects/:projectRef/supauth/reconcile`
84
+ - `POST /v1/projects/:projectRef/supauth/rollback`
85
+ - `GET /v1/projects/:projectRef/supauth/client-config`
86
+ - `GET /v1/projects/:projectRef/supauth/verify`
87
+
88
+ Boundary:
89
+
90
+ - Use `@supacloud/js` for SupaCloud-owned infrastructure orchestration: GoTrue env injection, restart/reconcile, Kong route setup, runtime health checks, and public client config discovery.
91
+ - Use `@supabase/supabase-js` for normal application runtime calls: auth session, database, storage, realtime, and edge functions.
92
+ - Use the SupaOAuth product SDK or Management API for SupaOAuth-owned resources: applications, connectors, organizations, roles, permissions, audit logs, and webhooks.
93
+ - Do not expose SupaCloud Management API credentials in browser code.
94
+
43
95
  ## Design
44
96
 
45
97
  This SDK is intentionally thin:
@@ -50,6 +102,8 @@ This SDK is intentionally thin:
50
102
  `tasks.submit()` expects the target function path to be configured in `background_routes`.
51
103
  That keeps frontend calls compatible with strict CORS deployments while preserving the same task receipt API.
52
104
 
105
+ Use `correlationId`, `businessTaskId`, and `metadata` when the application already has its own task, workflow, or billing records. SupaCloud stores these fields but does not interpret them; lifecycle webhooks echo them back so the application can update its own tables.
106
+
53
107
  The current package focuses on:
54
108
 
55
109
  - `tasks.submit`
@@ -78,6 +132,11 @@ The current package focuses on:
78
132
  - `auth.oauthServer.getJwks`
79
133
  - `auth.oauthServer.buildAuthorizeUrl`
80
134
  - `auth.oauthClients.list/create/get/update/delete/regenerateSecret`
135
+ - `supauth.provision`
136
+ - `supauth.reconcile`
137
+ - `supauth.rollback`
138
+ - `supauth.getClientConfig`
139
+ - `supauth.verify`
81
140
 
82
141
  ## Status Subscription
83
142
 
@@ -88,6 +147,37 @@ The current package focuses on:
88
147
 
89
148
  This lets apps degrade gracefully when websocket or channel health is transient.
90
149
 
150
+ ## Task Lifecycle Webhook
151
+
152
+ Applications that already own a business task table should keep it. SupaCloud emits lifecycle events so the app can sync `public.tasks`, billing, Realtime, and workflow rows without adopting platform-internal mirror tables.
153
+
154
+ Register a webhook from a trusted backend:
155
+
156
+ ```http
157
+ POST /v1/projects/:ref/task-events/webhook
158
+ Authorization: Bearer <management-token>
159
+ Content-Type: application/json
160
+
161
+ {
162
+ "url": "https://app.example.com/supacloud/task-events",
163
+ "secret": "shared-hmac-secret"
164
+ }
165
+ ```
166
+
167
+ Events are delivered as `{ events: [...] }`. Each event includes `event_type`, `task_id`, `status`, `attempt`, `correlation_id`, `business_task_id`, and `metadata`.
168
+
169
+ Supported lifecycle events:
170
+
171
+ - `task.created`
172
+ - `task.running`
173
+ - `task.succeeded`
174
+ - `task.failed`
175
+ - `task.retry_scheduled`
176
+ - `task.dead_lettered`
177
+ - `task.cancelled`
178
+
179
+ If `secret` is set, verify `X-SupaCloud-Signature: sha256=<hmac>` against the raw JSON body.
180
+
91
181
  ## Queue Helpers
92
182
 
93
183
  ```ts
@@ -97,9 +187,15 @@ const message = await queue.send(
97
187
  { to: "user@example.com", template: "welcome" },
98
188
  {
99
189
  idempotencyKey: "welcome-user-123",
190
+ delayMs: 10_000,
191
+ maxAttempts: 5,
192
+ traceId: "trace-123",
100
193
  correlationId: "signup-123",
101
194
  businessTaskId: "email-job-123",
102
- metadata: { source: "signup" },
195
+ metadata: {
196
+ source: "signup",
197
+ billing_subject: "user-123",
198
+ },
103
199
  },
104
200
  );
105
201
 
@@ -117,6 +213,29 @@ const stats = await queue.stats();
117
213
  console.log(stats.inFlight, stats.deadLettered);
118
214
  ```
119
215
 
216
+ Queue API surface:
217
+
218
+ - `queue.send(payload, options)`: enqueue a message, optionally delayed and idempotent
219
+ - `queue.receive({ visibilityTimeoutSec })`: lease the next message, or return `null`
220
+ - `queue.ack(messageId, result)`: mark the leased message succeeded
221
+ - `queue.release(messageId, { delayMs, error })`: return the message to the queue later
222
+ - `queue.fail(messageId, { error, deadLetter })`: mark failed or dead-lettered
223
+ - `queue.retry(messageId)`: replay a dead-lettered message
224
+ - `queue.delete(messageId)`: cancel/delete a message
225
+ - `queue.list(filters)`: list messages by status, DLQ flag, and limit
226
+ - `queue.listFailed(limit)`: shortcut for DLQ messages
227
+ - `queue.get(messageId)`: read message detail, attempts, and latest logs
228
+ - `queue.stats()`: inspect queue depth and recent success/failure counts
229
+ - `queue.getSettings()`: read concurrency, lease, retry, and rate-limit settings
230
+ - `queue.updateSettings(settings)`: patch queue settings
231
+
232
+ Queue settings:
233
+
234
+ - `max_in_flight`: max concurrently leased/running messages for this queue
235
+ - `default_visibility_timeout_sec`: lease timeout used by `receive()`
236
+ - `max_attempts`: default retry budget for new messages
237
+ - `rate_limit_per_minute`: producer enqueue limit
238
+
120
239
  Queue conflicts such as replaying a non-DLQ message are surfaced as `SupaCloudApiError` with `status`, `code`, and `responseBody`, so callers do not need to parse raw `fetch` responses.
121
240
 
122
241
  ## OAuth/OIDC Helpers
package/dist/index.d.ts CHANGED
@@ -112,6 +112,76 @@ export type SupaCloudQueueSettings = {
112
112
  rate_limit_per_minute: number;
113
113
  };
114
114
  export type SupaCloudQueueSettingsUpdate = Partial<SupaCloudQueueSettings>;
115
+ export type SupaCloudSupAuthAdminMode = "sso" | "token" | "auto";
116
+ export type SupaCloudSupAuthStorageBucket = {
117
+ id: string;
118
+ public?: boolean;
119
+ fileSizeLimit?: number;
120
+ allowedMimeTypes?: string[];
121
+ };
122
+ export type SupaCloudSupAuthProvisionOptions = {
123
+ authDomain?: string;
124
+ apiDomain?: string;
125
+ adminMode?: SupaCloudSupAuthAdminMode;
126
+ adminSsoClientId?: string;
127
+ runtimeUrl?: string;
128
+ supaOAuthUrl?: string;
129
+ storageBuckets?: SupaCloudSupAuthStorageBucket[];
130
+ metadata?: Record<string, unknown>;
131
+ };
132
+ export type SupaCloudSupAuthReconcileOptions = {
133
+ dryRun?: boolean;
134
+ force?: boolean;
135
+ };
136
+ export type SupaCloudSupAuthStepResult = {
137
+ step: string;
138
+ status: "pending" | "running" | "succeeded" | "failed" | "skipped" | string;
139
+ message?: string;
140
+ details?: Record<string, unknown>;
141
+ };
142
+ export type SupaCloudSupAuthProvisionResult = {
143
+ projectRef: string;
144
+ status: "pending" | "running" | "succeeded" | "failed" | string;
145
+ steps?: SupaCloudSupAuthStepResult[];
146
+ raw?: unknown;
147
+ };
148
+ export type SupaCloudSupAuthReconcileResult = {
149
+ projectRef: string;
150
+ changed: boolean;
151
+ dryRun?: boolean;
152
+ steps?: SupaCloudSupAuthStepResult[];
153
+ raw?: unknown;
154
+ };
155
+ export type SupaCloudSupAuthRollbackResult = {
156
+ projectRef: string;
157
+ status: "succeeded" | "failed" | string;
158
+ steps?: SupaCloudSupAuthStepResult[];
159
+ raw?: unknown;
160
+ };
161
+ export type SupaCloudSupAuthClientConfig = {
162
+ projectRef: string;
163
+ supabaseUrl: string;
164
+ anonKey?: string | null;
165
+ authUrl: string;
166
+ restUrl: string;
167
+ storageUrl: string;
168
+ realtimeUrl: string;
169
+ functionsUrl: string;
170
+ issuer?: string | null;
171
+ jwksUrl?: string | null;
172
+ metadata?: Record<string, unknown>;
173
+ };
174
+ export type SupaCloudSupAuthVerificationCheck = {
175
+ name: string;
176
+ status: "pass" | "fail" | "warn" | string;
177
+ message?: string;
178
+ details?: Record<string, unknown>;
179
+ };
180
+ export type SupaCloudSupAuthVerification = {
181
+ projectRef: string;
182
+ healthy: boolean;
183
+ checks: SupaCloudSupAuthVerificationCheck[];
184
+ };
115
185
  export type SupaCloudTaskWaitOptions = {
116
186
  intervalMs?: number;
117
187
  signal?: AbortSignal;
@@ -275,6 +345,14 @@ declare class SupaCloudOAuthClientsClient<TClient extends SupabaseClient = Supab
275
345
  delete(clientId: string): Promise<void>;
276
346
  regenerateSecret(clientId: string): Promise<SupaCloudOAuthClient>;
277
347
  }
348
+ declare class SupaCloudSupAuthClient<TClient extends SupabaseClient = SupabaseClient> extends SupaCloudManagementClient<TClient> {
349
+ private get basePath();
350
+ provision(options?: SupaCloudSupAuthProvisionOptions): Promise<SupaCloudSupAuthProvisionResult>;
351
+ reconcile(options?: SupaCloudSupAuthReconcileOptions): Promise<SupaCloudSupAuthReconcileResult>;
352
+ rollback(): Promise<SupaCloudSupAuthRollbackResult>;
353
+ getClientConfig(): Promise<SupaCloudSupAuthClientConfig>;
354
+ verify(): Promise<SupaCloudSupAuthVerification>;
355
+ }
278
356
  export declare function createSupaCloudClient<TClient extends SupabaseClient = SupabaseClient>(options: SupaCloudClientOptions<TClient>): {
279
357
  supabase: TClient;
280
358
  projectRef: string;
@@ -284,6 +362,7 @@ export declare function createSupaCloudClient<TClient extends SupabaseClient = S
284
362
  oauthClients: SupaCloudOAuthClientsClient<TClient>;
285
363
  };
286
364
  tasks: SupaCloudTasksClient<TClient>;
365
+ supauth: SupaCloudSupAuthClient<TClient>;
287
366
  queue: (name: string) => SupaCloudQueueClient<TClient>;
288
367
  functions: {
289
368
  invokeBackground: (functionName: string, submitOptions?: SupaCloudTaskSubmitOptions) => Promise<SupaCloudTaskReceipt>;
package/dist/index.js CHANGED
@@ -484,6 +484,27 @@ class SupaCloudOAuthClientsClient extends SupaCloudManagementClient {
484
484
  return this.request(`/v1/projects/${this.options.projectRef}/auth/oauth-clients/${encodeURIComponent(clientId)}/regenerate-secret`, "POST");
485
485
  }
486
486
  }
487
+
488
+ class SupaCloudSupAuthClient extends SupaCloudManagementClient {
489
+ get basePath() {
490
+ return `/v1/projects/${this.options.projectRef}/supauth`;
491
+ }
492
+ async provision(options = {}) {
493
+ return this.request(`${this.basePath}/provision`, "POST", options);
494
+ }
495
+ async reconcile(options = {}) {
496
+ return this.request(`${this.basePath}/reconcile`, "POST", options);
497
+ }
498
+ async rollback() {
499
+ return this.request(`${this.basePath}/rollback`, "POST");
500
+ }
501
+ async getClientConfig() {
502
+ return this.request(`${this.basePath}/client-config`, "GET");
503
+ }
504
+ async verify() {
505
+ return this.request(`${this.basePath}/verify`, "GET");
506
+ }
507
+ }
487
508
  function createSupaCloudClient(options) {
488
509
  const normalized = {
489
510
  ...options,
@@ -494,6 +515,7 @@ function createSupaCloudClient(options) {
494
515
  const tasks = new SupaCloudTasksClient(normalized);
495
516
  const oauthServer = new SupaCloudOAuthServerClient(normalized);
496
517
  const oauthClients = new SupaCloudOAuthClientsClient(normalized);
518
+ const supauth = new SupaCloudSupAuthClient(normalized);
497
519
  return {
498
520
  supabase: options.supabase,
499
521
  projectRef: normalized.projectRef,
@@ -503,6 +525,7 @@ function createSupaCloudClient(options) {
503
525
  oauthClients
504
526
  },
505
527
  tasks,
528
+ supauth,
506
529
  queue: (name) => new SupaCloudQueueClient(normalized, name),
507
530
  functions: {
508
531
  invokeBackground: (functionName, submitOptions) => tasks.submit(functionName, submitOptions)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@supacloud/js",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
4
4
  "description": "Platform SDK for SupaCloud, built on top of supabase-js",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",