@supacloud/js 0.16.1 → 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
 
@@ -46,6 +47,51 @@ const finalState = await task.wait();
46
47
  console.log(finalState.status);
47
48
  ```
48
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
+
49
95
  ## Design
50
96
 
51
97
  This SDK is intentionally thin:
@@ -86,6 +132,11 @@ The current package focuses on:
86
132
  - `auth.oauthServer.getJwks`
87
133
  - `auth.oauthServer.buildAuthorizeUrl`
88
134
  - `auth.oauthClients.list/create/get/update/delete/regenerateSecret`
135
+ - `supauth.provision`
136
+ - `supauth.reconcile`
137
+ - `supauth.rollback`
138
+ - `supauth.getClientConfig`
139
+ - `supauth.verify`
89
140
 
90
141
  ## Status Subscription
91
142
 
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.1",
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",