@faable/auth-sdk 1.3.13 → 1.3.15

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.
Files changed (6) hide show
  1. package/.github/workflows/release.yml +0 -1
  2. package/.github/workflows/sync-from-auth.yml +77 -0
  3. package/README.md +146 -24
  4. package/dist/FaableAuthApi.d.ts +50 -0
  5. package/dist/api/types.d.ts +1558 -323
  6. package/package.json +2 -2
package/.github/workflows/release.yml CHANGED
@@ -27,4 +27,3 @@ jobs:
27
27
  - run: npm run release
28
28
  env:
29
29
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
30
- NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
package/.github/workflows/sync-from-auth.yml ADDED
@@ -0,0 +1,77 @@
1
+ name: Sync from Auth
2
+ permissions:
3
+ contents: write # push del commit de tipos
4
+ pull-requests: write
5
+ issues: write
6
+ id-token: write # OIDC para publicar en npm (igual que release.yml)
7
+ on:
8
+ repository_dispatch:
9
+ types: [auth-released]
10
+ workflow_dispatch:
11
+ inputs:
12
+ version:
13
+ description: Auth version to sync (e.g. 1.8.12)
14
+ required: true
15
+ jobs:
16
+ sync:
17
+ name: sync
18
+ runs-on: ubuntu-latest
19
+ timeout-minutes: 10
20
+ env:
21
+ AUTH_OPENAPI: openapi.json # gentypes lee este archivo en vez de la URL viva
22
+ steps:
23
+ - uses: actions/checkout@v6
24
+ with:
25
+ ref: main
26
+ fetch-depth: 0
27
+ - uses: actions/setup-node@v6
28
+ with:
29
+ cache: npm
30
+ node-version: lts/*
31
+ - run: npm ci
32
+
33
+ - name: Resolve version
34
+ id: ver
35
+ run: echo "version=${{ github.event.client_payload.version || inputs.version }}" >> "$GITHUB_OUTPUT"
36
+
37
+ - name: Generate app token
38
+ id: app-token
39
+ uses: actions/create-github-app-token@v2
40
+ with:
41
+ app-id: ${{ secrets.APP_SYNC_SDK_ID }}
42
+ private-key: ${{ secrets.APP_SYNC_SDK_PRIVATE_KEY }}
43
+ owner: faablecloud
44
+ repositories: auth
45
+
46
+ - name: Download OpenAPI spec from auth release
47
+ env:
48
+ GH_TOKEN: ${{ steps.app-token.outputs.token }} # lee releases de faablecloud/auth (privado)
49
+ VERSION: ${{ steps.ver.outputs.version }}
50
+ run: gh release download "v$VERSION" --repo faablecloud/auth --pattern openapi.json --output openapi.json
51
+
52
+ - run: npm run gentypes # usa AUTH_OPENAPI=openapi.json
53
+
54
+ - name: Commit regenerated types
55
+ id: commit
56
+ env:
57
+ VERSION: ${{ steps.ver.outputs.version }}
58
+ run: |
59
+ if git diff --quiet -- src/api/types.ts; then
60
+ echo "changed=false" >> "$GITHUB_OUTPUT"
61
+ echo "Sin cambios de API para auth v$VERSION; no se publica."
62
+ exit 0
63
+ fi
64
+ git config user.name "github-actions[bot]"
65
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
66
+ git add src/api/types.ts
67
+ git commit -m "fix: sync with auth v$VERSION"
68
+ git push origin main
69
+ echo "changed=true" >> "$GITHUB_OUTPUT"
70
+
71
+ - run: npm run build
72
+ if: steps.commit.outputs.changed == 'true'
73
+ - run: npm run release
74
+ if: steps.commit.outputs.changed == 'true'
75
+ env:
76
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
77
+ NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  <p align="center">
2
2
  <a href="https://faable.com">
3
- <h1 align="center">Faable Auth SDK Client</h1>
3
+ <h1 align="center">Faable Auth SDK</h1>
4
4
  </a>
5
- <p align="center">Faable Auth management and auth API Client</p>
5
+ <p align="center">Server-side client for the FaableAuth administrative REST API.</p>
6
6
  </p>
7
7
 
8
8
  <p align="center">
@@ -11,54 +11,176 @@
11
11
  </a>
12
12
  </p>
13
13
 
14
- Programmatically perform FaableAuth administrative tasks though our REST API.
14
+ Programmatically manage FaableAuth users, teams, connections and clients through the FaableAuth REST API.
15
15
 
16
- > ⚠️ Use this library in server side only. Otherwise administrative credentials may be exposed.
16
+ > ⚠️ **Server-side only.** This SDK uses administrative credentials. Never ship it to a browser or any untrusted runtime.
17
+
18
+ ---
17
19
 
18
20
  ## Install
19
21
 
20
22
  ```bash
21
- npm install @faable/auth-sdk
23
+ npm install @faable/auth-sdk
22
24
  ```
23
25
 
24
- ## Config
26
+ ## Authentication
27
+
28
+ The SDK accepts any auth strategy from [`@faable/sdk-base`](https://www.npmjs.com/package/@faable/sdk-base). Two strategies are typically used:
29
+
30
+ ### Client credentials (recommended)
31
+
32
+ Reads `FAABLE_CLIENT_ID`, `FAABLE_CLIENT_SECRET` and `FAABLE_DOMAIN` from the environment by default:
25
33
 
26
- ```js
34
+ ```ts
27
35
  import { FaableAuthApi } from "@faable/auth-sdk";
28
36
  import { createClientCredentials } from "@faable/sdk-base";
29
37
 
30
- const auth = createClientCredentials();
38
+ const api = FaableAuthApi.create({
39
+ auth: createClientCredentials(),
40
+ team_id: "team_xxxxxxxxxxxxxxxxxxxxxxxx",
41
+ });
42
+ ```
43
+
44
+ You may also pass credentials explicitly:
45
+
46
+ ```ts
47
+ const auth = createClientCredentials({
48
+ client_id: process.env.FAABLE_CLIENT_ID!,
49
+ client_secret: process.env.FAABLE_CLIENT_SECRET!,
50
+ domain: "faable.auth.faable.link",
51
+ });
52
+ ```
53
+
54
+ ### API key
55
+
56
+ ```ts
57
+ import { FaableAuthApi } from "@faable/auth-sdk";
58
+ import { createApikeyAuth } from "@faable/sdk-base";
31
59
 
32
60
  const api = FaableAuthApi.create({
33
- auth,
34
- team: "<faable_team_id>",
61
+ auth: createApikeyAuth("fak_xxxxxxxxxxxxxxxx"),
62
+ team_id: "team_xxxxxxxxxxxxxxxxxxxxxxxx",
35
63
  });
36
64
  ```
37
65
 
66
+ ### Constructor options
67
+
68
+ | Option | Type | Description |
69
+ | ------------ | -------- | -------------------------------------------------------------------------------------------- |
70
+ | `auth` | strategy | Auth strategy from `@faable/sdk-base`. Required. |
71
+ | `team_id` | string | Scopes calls to a specific team (sent as `x-faable-team` header). |
72
+ | `account_id` | string | Scopes calls to a specific FaableAuth account (sent as `x-faableauth-account` header). |
73
+ | `domain` | string | Override the API host. Defaults to `https://faable.auth.faable.link`. |
74
+ | `debug` | boolean | Enables verbose logging in the underlying fetcher. |
75
+
76
+ ---
77
+
38
78
  ## Usage
39
79
 
40
- Get user:
80
+ ### Users
81
+
82
+ ```ts
83
+ // Get a user
84
+ const user = await api.getUser("user_xxx");
85
+
86
+ // Create a user
87
+ const created = await api.createUser({
88
+ email: "demo@example.com",
89
+ password: "•••••••••",
90
+ });
41
91
 
42
- ```js
43
- const user = await api.getUser("<user_id>");
92
+ // Update a user
93
+ const updated = await api.updateUser("user_xxx", { phone: "+34XXXXXXXXX" });
94
+
95
+ // List users (paginated) — first page of 30
96
+ const firstPage = await api.listUsers().first();
97
+
98
+ // Filter by email
99
+ const matches = await api.listUsers({ email: "demo@example.com" }).first();
100
+
101
+ // Iterate every page
102
+ for await (const page of api.listUsers()) {
103
+ for (const user of page) {
104
+ // ...
105
+ }
106
+ }
44
107
  ```
45
108
 
46
- Update user:
109
+ ### User metadata
47
110
 
48
- ```js
49
- const updated_user = await api.updateUser("<user_id>", {
50
- phone: "+34XXXXXXXXX",
111
+ ```ts
112
+ const metadata = await api.getUserMetadata("user_xxx");
113
+
114
+ await api.setUserMetadata("user_xxx", {
115
+ onboarded: true,
116
+ plan: "pro",
51
117
  });
52
118
  ```
53
119
 
54
- List users:
120
+ ### Teams
121
+
122
+ ```ts
123
+ const team = await api.getTeam("team_xxx");
124
+
125
+ const newTeam = await api.createTeam({ name: "Acme Inc." });
55
126
 
56
- ```js
57
- // Returns first page of latest 30 users
58
- const users = await api.listUsers().first();
127
+ await api.deleteTeam("team_xxx");
128
+
129
+ const myTeams = await api.listTeams({ user_id: "user_xxx" }).first();
59
130
  ```
60
131
 
61
- ```js
62
- // Query users with email=demo@example.com
63
- const users = await api.listUsers({ email: "demo@example.com" }).first();
132
+ ### Team members
133
+
134
+ ```ts
135
+ const members = await api.listTeamMembers({ query: "alice" }).first();
136
+
137
+ const isMember = await api.isUserMemberOfTeam("user_xxx", "team_xxx");
64
138
  ```
139
+
140
+ ### Connections
141
+
142
+ ```ts
143
+ const connections = await api.listConections().first();
144
+ const connection = await api.getConection("conn_xxx");
145
+ ```
146
+
147
+ ### Clients
148
+
149
+ ```ts
150
+ const clients = await api.listClients().first();
151
+ const client = await api.getClient("client_xxx");
152
+ ```
153
+
154
+ ### Current account
155
+
156
+ ```ts
157
+ const account = await api.currentAccount();
158
+ ```
159
+
160
+ ---
161
+
162
+ ## Pagination
163
+
164
+ List methods return a paginator. Use `.first()` to grab the first page or iterate with `for await ... of` to walk all pages:
165
+
166
+ ```ts
167
+ const paginator = api.listUsers();
168
+
169
+ const firstPage = await paginator.first();
170
+
171
+ for await (const page of paginator) {
172
+ // each `page` is an array of items
173
+ }
174
+ ```
175
+
176
+ ## Types
177
+
178
+ All response shapes are generated from the OpenAPI spec and re-exported from the package root:
179
+
180
+ ```ts
181
+ import type { User, Team, TeamMember, Connection, Client } from "@faable/auth-sdk";
182
+ ```
183
+
184
+ ## License
185
+
186
+ MIT
package/dist/FaableAuthApi.d.ts CHANGED
@@ -28,6 +28,7 @@ export declare class FaableAuthApi extends FaableApi {
28
28
  team?: string | null | undefined;
29
29
  notification_settings: {
30
30
  welcome_email_enabled: boolean;
31
+ verify_email_auto_send: boolean;
31
32
  };
32
33
  email_change_verification_mode?: "new_only" | "old_and_new" | undefined;
33
34
  email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
@@ -47,9 +48,13 @@ export declare class FaableAuthApi extends FaableApi {
47
48
  nickname?: string | null | undefined;
48
49
  email?: string | null | undefined;
49
50
  email_verified: boolean;
51
+ email_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
52
+ email_verified_at?: string | null | undefined;
50
53
  email_change_locked_at?: string | null | undefined;
51
54
  phone?: string | null | undefined;
52
55
  phone_verified: boolean;
56
+ phone_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
57
+ phone_verified_at?: string | null | undefined;
53
58
  country_iso?: string | null | undefined;
54
59
  birth_date?: string | null | undefined;
55
60
  gender?: string | null | undefined;
@@ -92,9 +97,13 @@ export declare class FaableAuthApi extends FaableApi {
92
97
  nickname?: string | null | undefined;
93
98
  email?: string | null | undefined;
94
99
  email_verified: boolean;
100
+ email_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
101
+ email_verified_at?: string | null | undefined;
95
102
  email_change_locked_at?: string | null | undefined;
96
103
  phone?: string | null | undefined;
97
104
  phone_verified: boolean;
105
+ phone_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
106
+ phone_verified_at?: string | null | undefined;
98
107
  country_iso?: string | null | undefined;
99
108
  birth_date?: string | null | undefined;
100
109
  gender?: string | null | undefined;
@@ -140,9 +149,13 @@ export declare class FaableAuthApi extends FaableApi {
140
149
  nickname?: string | null | undefined;
141
150
  email?: string | null | undefined;
142
151
  email_verified: boolean;
152
+ email_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
153
+ email_verified_at?: string | null | undefined;
143
154
  email_change_locked_at?: string | null | undefined;
144
155
  phone?: string | null | undefined;
145
156
  phone_verified: boolean;
157
+ phone_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
158
+ phone_verified_at?: string | null | undefined;
146
159
  country_iso?: string | null | undefined;
147
160
  birth_date?: string | null | undefined;
148
161
  gender?: string | null | undefined;
@@ -186,9 +199,13 @@ export declare class FaableAuthApi extends FaableApi {
186
199
  nickname?: string | null | undefined;
187
200
  email?: string | null | undefined;
188
201
  email_verified: boolean;
202
+ email_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
203
+ email_verified_at?: string | null | undefined;
189
204
  email_change_locked_at?: string | null | undefined;
190
205
  phone?: string | null | undefined;
191
206
  phone_verified: boolean;
207
+ phone_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
208
+ phone_verified_at?: string | null | undefined;
192
209
  country_iso?: string | null | undefined;
193
210
  birth_date?: string | null | undefined;
194
211
  gender?: string | null | undefined;
@@ -231,9 +248,13 @@ export declare class FaableAuthApi extends FaableApi {
231
248
  nickname?: string | null | undefined;
232
249
  email?: string | null | undefined;
233
250
  email_verified: boolean;
251
+ email_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
252
+ email_verified_at?: string | null | undefined;
234
253
  email_change_locked_at?: string | null | undefined;
235
254
  phone?: string | null | undefined;
236
255
  phone_verified: boolean;
256
+ phone_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
257
+ phone_verified_at?: string | null | undefined;
237
258
  country_iso?: string | null | undefined;
238
259
  birth_date?: string | null | undefined;
239
260
  gender?: string | null | undefined;
@@ -276,9 +297,13 @@ export declare class FaableAuthApi extends FaableApi {
276
297
  nickname?: string | null | undefined;
277
298
  email?: string | null | undefined;
278
299
  email_verified: boolean;
300
+ email_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
301
+ email_verified_at?: string | null | undefined;
279
302
  email_change_locked_at?: string | null | undefined;
280
303
  phone?: string | null | undefined;
281
304
  phone_verified: boolean;
305
+ phone_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | null | undefined;
306
+ phone_verified_at?: string | null | undefined;
282
307
  country_iso?: string | null | undefined;
283
308
  birth_date?: string | null | undefined;
284
309
  gender?: string | null | undefined;
@@ -447,6 +472,11 @@ export declare class FaableAuthApi extends FaableApi {
447
472
  authorize_params: {
448
473
  [key: string]: string;
449
474
  };
475
+ claims_mapping?: {
476
+ [key: string]: string;
477
+ } | undefined;
478
+ readonly is_using_default_credentials: boolean;
479
+ email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
450
480
  account: string;
451
481
  metadata: {
452
482
  [key: string]: unknown;
@@ -472,6 +502,11 @@ export declare class FaableAuthApi extends FaableApi {
472
502
  authorize_params: {
473
503
  [key: string]: string;
474
504
  };
505
+ claims_mapping?: {
506
+ [key: string]: string;
507
+ } | undefined;
508
+ readonly is_using_default_credentials: boolean;
509
+ email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
475
510
  account: string;
476
511
  metadata: {
477
512
  [key: string]: unknown;
@@ -500,6 +535,11 @@ export declare class FaableAuthApi extends FaableApi {
500
535
  authorize_params: {
501
536
  [key: string]: string;
502
537
  };
538
+ claims_mapping?: {
539
+ [key: string]: string;
540
+ } | undefined;
541
+ readonly is_using_default_credentials: boolean;
542
+ email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
503
543
  account: string;
504
544
  metadata: {
505
545
  [key: string]: unknown;
@@ -526,6 +566,11 @@ export declare class FaableAuthApi extends FaableApi {
526
566
  authorize_params: {
527
567
  [key: string]: string;
528
568
  };
569
+ claims_mapping?: {
570
+ [key: string]: string;
571
+ } | undefined;
572
+ readonly is_using_default_credentials: boolean;
573
+ email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
529
574
  account: string;
530
575
  metadata: {
531
576
  [key: string]: unknown;
@@ -657,6 +702,11 @@ export declare class FaableAuthApi extends FaableApi {
657
702
  authorize_params: {
658
703
  [key: string]: string;
659
704
  };
705
+ claims_mapping?: {
706
+ [key: string]: string;
707
+ } | undefined;
708
+ readonly is_using_default_credentials: boolean;
709
+ email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
660
710
  account: string;
661
711
  metadata: {
662
712
  [key: string]: unknown;