@faable/auth-sdk 1.3.34 → 2.0.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.
Files changed (8) hide show
  1. package/README.md +35 -22
  2. package/dist/FaableAuthApi.d.ts +20 -9
  3. package/dist/FaableAuthApi.js +10 -6
  4. package/dist/api/types.d.ts +10 -10
  5. package/dist/index.d.ts +2 -0
  6. package/dist/index.js +4 -0
  7. package/package.json +2 -2
  8. package/spec/openapi.json +17 -9
package/README.md CHANGED
@@ -25,53 +25,66 @@ npm install @faable/auth-sdk
25
25
 
26
26
  ## Authentication
27
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:
28
+ Auth is **explicit and pluggable**: you pick an `authStrategy` and pass its
29
+ config in `auth`. The SDK **never reads credentials from the environment** —
30
+ read them yourself and pass them in. The strategy you choose drives the type of
31
+ `auth`, so the editor autocompletes the right fields. The strategies are
32
+ re-exported from `@faable/auth-sdk`, so you only ever import from this package.
33
+
34
+ > **Breaking change (v2):** the old `createClientCredentials()` /
35
+ > `createApikeyAuth()` helpers (which read `FAABLE_*` env vars automatically)
36
+ > were removed. Use the `authStrategy` + `auth` pair below. `domain` is now
37
+ > **required** — there is no hardcoded default host anymore.
29
38
 
30
39
  ### Client credentials (recommended)
31
40
 
32
- Reads `FAABLE_CLIENT_ID`, `FAABLE_CLIENT_SECRET` and `FAABLE_DOMAIN` from the environment by default:
41
+ `authClientCredentials` is the **default** strategy, so you only pass `auth`
42
+ with `{ client_id, client_secret }` — no need to set `authStrategy`:
33
43
 
34
44
  ```ts
35
45
  import { FaableAuthApi } from "@faable/auth-sdk";
36
- import { createClientCredentials } from "@faable/sdk-base";
37
46
 
38
47
  const api = FaableAuthApi.create({
39
- auth: createClientCredentials(),
40
- team_id: "team_xxxxxxxxxxxxxxxxxxxxxxxx",
48
+ domain: "https://<your-account>.auth.faable.link",
49
+ auth: {
50
+ client_id: process.env.FAABLEAUTH_CLIENT_ID!,
51
+ client_secret: process.env.FAABLEAUTH_CLIENT_SECRET!,
52
+ },
41
53
  });
42
54
  ```
43
55
 
44
- You may also pass credentials explicitly:
56
+ By default the token is requested from `<domain>/oauth/token`. If your API host
57
+ is **not** the auth server, override it with `auth.domain`:
45
58
 
46
59
  ```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
- });
60
+ auth: {
61
+ client_id: "...",
62
+ client_secret: "...",
63
+ domain: "https://<your-account>.auth.faable.link", // where /oauth/token lives
64
+ }
52
65
  ```
53
66
 
54
67
  ### API key
55
68
 
56
69
  ```ts
57
- import { FaableAuthApi } from "@faable/auth-sdk";
58
- import { createApikeyAuth } from "@faable/sdk-base";
70
+ import { FaableAuthApi, authApikey } from "@faable/auth-sdk";
59
71
 
60
72
  const api = FaableAuthApi.create({
61
- auth: createApikeyAuth("fak_xxxxxxxxxxxxxxxx"),
62
- team_id: "team_xxxxxxxxxxxxxxxxxxxxxxxx",
73
+ domain: "https://<your-account>.auth.faable.link",
74
+ authStrategy: authApikey,
75
+ auth: { apikey: "fak_xxxxxxxxxxxxxxxx" },
63
76
  });
64
77
  ```
65
78
 
66
79
  ### Constructor options
67
80
 
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. |
81
+ | Option | Type | Description |
82
+ | -------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
83
+ | `domain` | string | **Required.** The account host to target, e.g. `https://<your-account>.auth.faable.link`. No default. |
84
+ | `authStrategy` | strategy builder | Auth strategy (`authClientCredentials` \| `authApikey`), re-exported from `@faable/auth-sdk`. Defaults to `authClientCredentials`. |
85
+ | `auth` | config | Config for the chosen strategy. Its shape is inferred from `authStrategy` (e.g. `{ client_id, client_secret }`). |
86
+ | `debug` | boolean | Enables verbose logging in the underlying fetcher. |
87
+ | `headers` | `{ team_id?; account_id? }` | Advanced / testing escape hatch — target `domain` but have the server resolve a different team/account (sent as `x-faable-team` / `x-faableauth-account`). |
75
88
 
76
89
  ---
77
90
 
package/dist/FaableAuthApi.d.ts CHANGED
@@ -1,9 +1,20 @@
1
1
  import { TeamCreate, UserCreate, UserUpdate } from "./api/api-types.js";
2
2
  import { ApiParams, FaableApi } from "@faable/sdk-base";
3
3
  type FaableAuthApiParams = {
4
- team_id?: string;
5
- account_id?: string;
6
- domain?: string;
4
+ domain: string;
5
+ /**
6
+ * Advanced / testing escape hatch: keep targeting `domain` but have the
7
+ * server resolve a DIFFERENT team or account, via request headers. Only the
8
+ * dashboard and some tests need this (e.g. point at a concrete host but
9
+ * resolve another account) — it is intentionally kept out of the normal
10
+ * config surface. Maps to:
11
+ * - `team_id` → `x-faable-team`
12
+ * - `account_id` → `x-faableauth-account`
13
+ */
14
+ headers?: {
15
+ team_id?: string;
16
+ account_id?: string;
17
+ };
7
18
  } & ApiParams;
8
19
  export declare class FaableAuthApi extends FaableApi {
9
20
  constructor(params?: FaableAuthApiParams);
@@ -60,7 +71,7 @@ export declare class FaableAuthApi extends FaableApi {
60
71
  birth_date?: string | null | undefined;
61
72
  gender?: string | null | undefined;
62
73
  zoneinfo?: string | null | undefined;
63
- locale?: string | undefined;
74
+ locale?: string | null | undefined;
64
75
  region?: string | null | undefined;
65
76
  website?: string | null | undefined;
66
77
  address?: {
@@ -110,7 +121,7 @@ export declare class FaableAuthApi extends FaableApi {
110
121
  birth_date?: string | null | undefined;
111
122
  gender?: string | null | undefined;
112
123
  zoneinfo?: string | null | undefined;
113
- locale?: string | undefined;
124
+ locale?: string | null | undefined;
114
125
  region?: string | null | undefined;
115
126
  website?: string | null | undefined;
116
127
  address?: {
@@ -163,7 +174,7 @@ export declare class FaableAuthApi extends FaableApi {
163
174
  birth_date?: string | null | undefined;
164
175
  gender?: string | null | undefined;
165
176
  zoneinfo?: string | null | undefined;
166
- locale?: string | undefined;
177
+ locale?: string | null | undefined;
167
178
  region?: string | null | undefined;
168
179
  website?: string | null | undefined;
169
180
  address?: {
@@ -214,7 +225,7 @@ export declare class FaableAuthApi extends FaableApi {
214
225
  birth_date?: string | null | undefined;
215
226
  gender?: string | null | undefined;
216
227
  zoneinfo?: string | null | undefined;
217
- locale?: string | undefined;
228
+ locale?: string | null | undefined;
218
229
  region?: string | null | undefined;
219
230
  website?: string | null | undefined;
220
231
  address?: {
@@ -264,7 +275,7 @@ export declare class FaableAuthApi extends FaableApi {
264
275
  birth_date?: string | null | undefined;
265
276
  gender?: string | null | undefined;
266
277
  zoneinfo?: string | null | undefined;
267
- locale?: string | undefined;
278
+ locale?: string | null | undefined;
268
279
  region?: string | null | undefined;
269
280
  website?: string | null | undefined;
270
281
  address?: {
@@ -314,7 +325,7 @@ export declare class FaableAuthApi extends FaableApi {
314
325
  birth_date?: string | null | undefined;
315
326
  gender?: string | null | undefined;
316
327
  zoneinfo?: string | null | undefined;
317
- locale?: string | undefined;
328
+ locale?: string | null | undefined;
318
329
  region?: string | null | undefined;
319
330
  website?: string | null | undefined;
320
331
  address?: {
package/dist/FaableAuthApi.js CHANGED
@@ -4,10 +4,12 @@ import { FaableApi } from "@faable/sdk-base";
4
4
  import { version } from "./version.js";
5
5
  export class FaableAuthApi extends FaableApi {
6
6
  constructor(params) {
7
- let baseURL = "https://faable.auth.faable.link";
8
- if (params?.domain) {
9
- baseURL = getDomain(params.domain);
7
+ if (!params?.domain) {
8
+ throw new FaableApiError("FaableAuthApi: `domain` is required. Pass your account host, e.g. " +
9
+ "`new FaableAuthApi({ domain: 'https://<your-account>.auth.faable.link', ... })`. " +
10
+ "The hardcoded default was removed so SDK calls never target another tenant by accident.");
10
11
  }
12
+ const baseURL = getDomain(params.domain);
11
13
  super({
12
14
  baseURL,
13
15
  ...params,
@@ -20,9 +22,11 @@ export class FaableAuthApi extends FaableApi {
20
22
  // canonical logs). Format: `<name>/<version>`.
21
23
  "x-faable-client": `auth-sdk/${version}`,
22
24
  ...params?.fetcher?.headers,
23
- ...(params?.team_id && { "x-faable-team": params.team_id }),
24
- ...(params?.account_id && {
25
- "x-faableauth-account": params.account_id,
25
+ ...(params?.headers?.team_id && {
26
+ "x-faable-team": params.headers.team_id,
27
+ }),
28
+ ...(params?.headers?.account_id && {
29
+ "x-faableauth-account": params.headers.account_id,
26
30
  }),
27
31
  },
28
32
  },
package/dist/api/types.d.ts CHANGED
@@ -1963,7 +1963,7 @@ export interface components {
1963
1963
  /** @description IANA time-zone name (e.g. "Europe/Madrid"). OIDC §5.1 — used for the `zoneinfo` claim. */
1964
1964
  zoneinfo?: string | null;
1965
1965
  /** @description user main language */
1966
- locale?: string;
1966
+ locale?: string | null;
1967
1967
  /** @description customer region */
1968
1968
  region?: string | null;
1969
1969
  /** @description URL of the User's personal Web page or blog (OIDC §5.1) */
@@ -2104,8 +2104,8 @@ export interface components {
2104
2104
  country_iso?: string;
2105
2105
  /** @description user birth_date */
2106
2106
  birth_date?: string;
2107
- /** @description user birth_date */
2108
- locale?: string;
2107
+ /** @description user main language */
2108
+ locale?: string | null;
2109
2109
  /** @description User picture url */
2110
2110
  picture?: string;
2111
2111
  /** @description User defined metadata */
@@ -4552,7 +4552,7 @@ export interface operations {
4552
4552
  /** @description IANA time-zone name (e.g. "Europe/Madrid"). OIDC §5.1 — used for the `zoneinfo` claim. */
4553
4553
  zoneinfo?: string | null;
4554
4554
  /** @description user main language */
4555
- locale?: string;
4555
+ locale?: string | null;
4556
4556
  /** @description customer region */
4557
4557
  region?: string | null;
4558
4558
  /** @description URL of the User's personal Web page or blog (OIDC §5.1) */
@@ -4673,7 +4673,7 @@ export interface operations {
4673
4673
  /** @description IANA time-zone name (e.g. "Europe/Madrid"). OIDC §5.1 — used for the `zoneinfo` claim. */
4674
4674
  zoneinfo?: string | null;
4675
4675
  /** @description user main language */
4676
- locale?: string;
4676
+ locale?: string | null;
4677
4677
  /** @description customer region */
4678
4678
  region?: string | null;
4679
4679
  /** @description URL of the User's personal Web page or blog (OIDC §5.1) */
@@ -4761,8 +4761,8 @@ export interface operations {
4761
4761
  country_iso?: string;
4762
4762
  /** @description user birth_date */
4763
4763
  birth_date?: string;
4764
- /** @description user birth_date */
4765
- locale?: string;
4764
+ /** @description user main language */
4765
+ locale?: string | null;
4766
4766
  /** @description User picture url */
4767
4767
  picture?: string;
4768
4768
  /** @description User defined metadata */
@@ -4830,7 +4830,7 @@ export interface operations {
4830
4830
  /** @description IANA time-zone name (e.g. "Europe/Madrid"). OIDC §5.1 — used for the `zoneinfo` claim. */
4831
4831
  zoneinfo?: string | null;
4832
4832
  /** @description user main language */
4833
- locale?: string;
4833
+ locale?: string | null;
4834
4834
  /** @description customer region */
4835
4835
  region?: string | null;
4836
4836
  /** @description URL of the User's personal Web page or blog (OIDC §5.1) */
@@ -4951,7 +4951,7 @@ export interface operations {
4951
4951
  /** @description IANA time-zone name (e.g. "Europe/Madrid"). OIDC §5.1 — used for the `zoneinfo` claim. */
4952
4952
  zoneinfo?: string | null;
4953
4953
  /** @description user main language */
4954
- locale?: string;
4954
+ locale?: string | null;
4955
4955
  /** @description customer region */
4956
4956
  region?: string | null;
4957
4957
  /** @description URL of the User's personal Web page or blog (OIDC §5.1) */
@@ -8409,7 +8409,7 @@ export interface operations {
8409
8409
  /** @description IANA time-zone name (e.g. "Europe/Madrid"). OIDC §5.1 — used for the `zoneinfo` claim. */
8410
8410
  zoneinfo?: string | null;
8411
8411
  /** @description user main language */
8412
- locale?: string;
8412
+ locale?: string | null;
8413
8413
  /** @description customer region */
8414
8414
  region?: string | null;
8415
8415
  /** @description URL of the User's personal Web page or blog (OIDC §5.1) */
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
1
  export * from "./FaableAuthApi.js";
2
2
  export * from "./api/api-types.js";
3
3
  export * from "./api/types.js";
4
+ export { authClientCredentials, authApikey } from "@faable/sdk-base";
5
+ export type { ApiParams, ClientCredentialsConfig, ApikeyConfig, AuthStrategy, AuthStrategyBuilder, AuthStrategyContext, } from "@faable/sdk-base";
package/dist/index.js CHANGED
@@ -1,3 +1,7 @@
1
1
  export * from "./FaableAuthApi.js";
2
2
  export * from "./api/api-types.js";
3
3
  export * from "./api/types.js";
4
+ // Re-export the auth strategies (and their config/types) from
5
+ // @faable/sdk-base so consumers depend on @faable/auth-sdk ONLY — sdk-base
6
+ // stays a transitive dependency and no app needs to import it directly.
7
+ export { authClientCredentials, authApikey } from "@faable/sdk-base";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/auth-sdk",
3
- "version": "1.3.34",
3
+ "version": "2.0.0",
4
4
  "author": "Marc Pomar <marc@faable.com>",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -10,7 +10,7 @@
10
10
  },
11
11
  "type": "module",
12
12
  "dependencies": {
13
- "@faable/sdk-base": "^1.1.2"
13
+ "@faable/sdk-base": "^1.5.0"
14
14
  },
15
15
  "devDependencies": {
16
16
  "@ava/typescript": "^5.0.0",
package/spec/openapi.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "info": {
4
4
  "title": "@faablecloud/auth",
5
5
  "description": "Auth Platform made by Faable. Manage Users and Roles",
6
- "version": "1.10.9",
6
+ "version": "1.10.10",
7
7
  "license": {
8
8
  "name": "private",
9
9
  "url": "https://faable.com/docs/platform/privacy-policy"
@@ -1235,7 +1235,8 @@
1235
1235
  },
1236
1236
  "locale": {
1237
1237
  "type": "string",
1238
- "description": "user main language"
1238
+ "description": "user main language",
1239
+ "nullable": true
1239
1240
  },
1240
1241
  "region": {
1241
1242
  "type": "string",
@@ -1497,7 +1498,8 @@
1497
1498
  },
1498
1499
  "locale": {
1499
1500
  "type": "string",
1500
- "description": "user birth_date"
1501
+ "description": "user main language",
1502
+ "nullable": true
1501
1503
  },
1502
1504
  "picture": {
1503
1505
  "type": "string",
@@ -8119,7 +8121,8 @@
8119
8121
  },
8120
8122
  "locale": {
8121
8123
  "type": "string",
8122
- "description": "user main language"
8124
+ "description": "user main language",
8125
+ "nullable": true
8123
8126
  },
8124
8127
  "region": {
8125
8128
  "type": "string",
@@ -8451,7 +8454,8 @@
8451
8454
  },
8452
8455
  "locale": {
8453
8456
  "type": "string",
8454
- "description": "user main language"
8457
+ "description": "user main language",
8458
+ "nullable": true
8455
8459
  },
8456
8460
  "region": {
8457
8461
  "type": "string",
@@ -8610,7 +8614,8 @@
8610
8614
  },
8611
8615
  "locale": {
8612
8616
  "type": "string",
8613
- "description": "user birth_date"
8617
+ "description": "user main language",
8618
+ "nullable": true
8614
8619
  },
8615
8620
  "picture": {
8616
8621
  "type": "string",
@@ -8852,7 +8857,8 @@
8852
8857
  },
8853
8858
  "locale": {
8854
8859
  "type": "string",
8855
- "description": "user main language"
8860
+ "description": "user main language",
8861
+ "nullable": true
8856
8862
  },
8857
8863
  "region": {
8858
8864
  "type": "string",
@@ -9182,7 +9188,8 @@
9182
9188
  },
9183
9189
  "locale": {
9184
9190
  "type": "string",
9185
- "description": "user main language"
9191
+ "description": "user main language",
9192
+ "nullable": true
9186
9193
  },
9187
9194
  "region": {
9188
9195
  "type": "string",
@@ -17178,7 +17185,8 @@
17178
17185
  },
17179
17186
  "locale": {
17180
17187
  "type": "string",
17181
- "description": "user main language"
17188
+ "description": "user main language",
17189
+ "nullable": true
17182
17190
  },
17183
17191
  "region": {
17184
17192
  "type": "string",