@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 +120 -1
- package/dist/index.d.ts +79 -0
- package/dist/index.js +23 -0
- package/package.json +1 -1
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: {
|
|
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)
|