@faable/auth-sdk 1.3.12 → 1.3.14
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 +146 -24
- package/dist/FaableAuthApi.d.ts +43 -0
- package/dist/api/types.d.ts +1209 -19
- package/package.json +1 -1
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
|
|
3
|
+
<h1 align="center">Faable Auth SDK</h1>
|
|
4
4
|
</a>
|
|
5
|
-
<p align="center">
|
|
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
|
|
14
|
+
Programmatically manage FaableAuth users, teams, connections and clients through the FaableAuth REST API.
|
|
15
15
|
|
|
16
|
-
> ⚠️
|
|
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
|
-
|
|
23
|
+
npm install @faable/auth-sdk
|
|
22
24
|
```
|
|
23
25
|
|
|
24
|
-
##
|
|
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
|
-
```
|
|
34
|
+
```ts
|
|
27
35
|
import { FaableAuthApi } from "@faable/auth-sdk";
|
|
28
36
|
import { createClientCredentials } from "@faable/sdk-base";
|
|
29
37
|
|
|
30
|
-
const
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
43
|
-
const
|
|
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
|
-
|
|
109
|
+
### User metadata
|
|
47
110
|
|
|
48
|
-
```
|
|
49
|
-
const
|
|
50
|
-
|
|
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
|
-
|
|
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
|
-
|
|
57
|
-
|
|
58
|
-
const
|
|
127
|
+
await api.deleteTeam("team_xxx");
|
|
128
|
+
|
|
129
|
+
const myTeams = await api.listTeams({ user_id: "user_xxx" }).first();
|
|
59
130
|
```
|
|
60
131
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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,7 +28,10 @@ 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
|
};
|
|
33
|
+
email_change_verification_mode?: "new_only" | "old_and_new" | undefined;
|
|
34
|
+
email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
|
|
32
35
|
createdAt: string;
|
|
33
36
|
updatedAt?: string | undefined;
|
|
34
37
|
}>;
|
|
@@ -45,8 +48,13 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
45
48
|
nickname?: string | null | undefined;
|
|
46
49
|
email?: string | null | undefined;
|
|
47
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;
|
|
53
|
+
email_change_locked_at?: string | null | undefined;
|
|
48
54
|
phone?: string | null | undefined;
|
|
49
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;
|
|
50
58
|
country_iso?: string | null | undefined;
|
|
51
59
|
birth_date?: string | null | undefined;
|
|
52
60
|
gender?: string | null | undefined;
|
|
@@ -89,8 +97,13 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
89
97
|
nickname?: string | null | undefined;
|
|
90
98
|
email?: string | null | undefined;
|
|
91
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;
|
|
102
|
+
email_change_locked_at?: string | null | undefined;
|
|
92
103
|
phone?: string | null | undefined;
|
|
93
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;
|
|
94
107
|
country_iso?: string | null | undefined;
|
|
95
108
|
birth_date?: string | null | undefined;
|
|
96
109
|
gender?: string | null | undefined;
|
|
@@ -136,8 +149,13 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
136
149
|
nickname?: string | null | undefined;
|
|
137
150
|
email?: string | null | undefined;
|
|
138
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;
|
|
154
|
+
email_change_locked_at?: string | null | undefined;
|
|
139
155
|
phone?: string | null | undefined;
|
|
140
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;
|
|
141
159
|
country_iso?: string | null | undefined;
|
|
142
160
|
birth_date?: string | null | undefined;
|
|
143
161
|
gender?: string | null | undefined;
|
|
@@ -181,8 +199,13 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
181
199
|
nickname?: string | null | undefined;
|
|
182
200
|
email?: string | null | undefined;
|
|
183
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;
|
|
204
|
+
email_change_locked_at?: string | null | undefined;
|
|
184
205
|
phone?: string | null | undefined;
|
|
185
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;
|
|
186
209
|
country_iso?: string | null | undefined;
|
|
187
210
|
birth_date?: string | null | undefined;
|
|
188
211
|
gender?: string | null | undefined;
|
|
@@ -225,8 +248,13 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
225
248
|
nickname?: string | null | undefined;
|
|
226
249
|
email?: string | null | undefined;
|
|
227
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;
|
|
253
|
+
email_change_locked_at?: string | null | undefined;
|
|
228
254
|
phone?: string | null | undefined;
|
|
229
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;
|
|
230
258
|
country_iso?: string | null | undefined;
|
|
231
259
|
birth_date?: string | null | undefined;
|
|
232
260
|
gender?: string | null | undefined;
|
|
@@ -269,8 +297,13 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
269
297
|
nickname?: string | null | undefined;
|
|
270
298
|
email?: string | null | undefined;
|
|
271
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;
|
|
302
|
+
email_change_locked_at?: string | null | undefined;
|
|
272
303
|
phone?: string | null | undefined;
|
|
273
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;
|
|
274
307
|
country_iso?: string | null | undefined;
|
|
275
308
|
birth_date?: string | null | undefined;
|
|
276
309
|
gender?: string | null | undefined;
|
|
@@ -439,6 +472,8 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
439
472
|
authorize_params: {
|
|
440
473
|
[key: string]: string;
|
|
441
474
|
};
|
|
475
|
+
readonly is_using_default_credentials: boolean;
|
|
476
|
+
email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
|
|
442
477
|
account: string;
|
|
443
478
|
metadata: {
|
|
444
479
|
[key: string]: unknown;
|
|
@@ -464,6 +499,8 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
464
499
|
authorize_params: {
|
|
465
500
|
[key: string]: string;
|
|
466
501
|
};
|
|
502
|
+
readonly is_using_default_credentials: boolean;
|
|
503
|
+
email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
|
|
467
504
|
account: string;
|
|
468
505
|
metadata: {
|
|
469
506
|
[key: string]: unknown;
|
|
@@ -492,6 +529,8 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
492
529
|
authorize_params: {
|
|
493
530
|
[key: string]: string;
|
|
494
531
|
};
|
|
532
|
+
readonly is_using_default_credentials: boolean;
|
|
533
|
+
email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
|
|
495
534
|
account: string;
|
|
496
535
|
metadata: {
|
|
497
536
|
[key: string]: unknown;
|
|
@@ -518,6 +557,8 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
518
557
|
authorize_params: {
|
|
519
558
|
[key: string]: string;
|
|
520
559
|
};
|
|
560
|
+
readonly is_using_default_credentials: boolean;
|
|
561
|
+
email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
|
|
521
562
|
account: string;
|
|
522
563
|
metadata: {
|
|
523
564
|
[key: string]: unknown;
|
|
@@ -649,6 +690,8 @@ export declare class FaableAuthApi extends FaableApi {
|
|
|
649
690
|
authorize_params: {
|
|
650
691
|
[key: string]: string;
|
|
651
692
|
};
|
|
693
|
+
readonly is_using_default_credentials: boolean;
|
|
694
|
+
email_oauth_sync_policy?: "preserve_manual" | "always_sync" | undefined;
|
|
652
695
|
account: string;
|
|
653
696
|
metadata: {
|
|
654
697
|
[key: string]: unknown;
|