@studio-design/studio-auth-node 0.3.2-rc.19 → 0.3.2-rc.21

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 (2) hide show
  1. package/README.md +99 -8
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,6 +2,23 @@
2
2
 
3
3
  TypeScript / JavaScript client for the Studio Auth Service API.
4
4
 
5
+ ## Documentation
6
+
7
+ The full API reference (all endpoints, schemas, and error responses) is
8
+ published on the Studio internal developer portal (Google IAP protected —
9
+ Studio members only). Open the portal top page and look for
10
+ "Auth Service API".
11
+
12
+ ## Requirements
13
+
14
+ - Node.js 18 or later is required (the SDK uses the global `fetch`). Run a
15
+ currently-maintained LTS line — see the
16
+ [Node.js release schedule](https://nodejs.org/en/about/previous-releases)
17
+ (Node.js 22 and 24 are the maintained LTS lines at the time of writing;
18
+ 18 and 20 have reached end-of-life).
19
+ - This package is **ESM-only** (`"type": "module"`). CommonJS `require()` is
20
+ not supported — use `import`.
21
+
5
22
  ## Install
6
23
 
7
24
  ### Stable
@@ -24,7 +41,7 @@ npm install @studio-design/studio-auth-node@next
24
41
  ```
25
42
 
26
43
  The snapshot version follows `<next-patch>-rc.<run_number>` (e.g. `0.2.25-rc.5`).
27
- See the [studio-auth-node Releases](https://github.com/studio-design/studio-auth-node/releases)
44
+ See the [studio-auth-node tags](https://github.com/studio-design/studio-auth-node/tags)
28
45
  for the latest snapshot tag.
29
46
 
30
47
  > ⚠️ Snapshot releases are intended for staging / CI validation. For production,
@@ -35,20 +52,50 @@ for the latest snapshot tag.
35
52
 
36
53
  ### Host configuration (required)
37
54
 
38
- The SDK does not ship with a default host URL. Configure the base URL before
39
- making any requests.
55
+ The generated client defaults to the local development server
56
+ (`https://auth.local.studio.design`, the first `servers` entry of the OpenAPI
57
+ spec). Always set `baseUrl` explicitly for the environment you target.
40
58
 
41
59
  ```ts
42
60
  import { client } from '@studio-design/studio-auth-node';
43
61
 
44
62
  client.setConfig({
45
63
  baseUrl: 'https://your-auth-server.example.com',
46
- auth: () => `Bearer ${accessToken}`,
64
+ auth: () => accessToken,
47
65
  });
48
66
  ```
49
67
 
50
68
  The SDK is generated from the Studio Auth Service OpenAPI specification.
51
69
 
70
+ ### Authentication
71
+
72
+ Operations use one of two security schemes, mirroring the OpenAPI spec:
73
+
74
+ | Scheme | Applies to | What the `auth` callback must return |
75
+ | --- | --- | --- |
76
+ | `BearerAuth` (JWT) | Admin / Organization operations, `getUserinfo` / `postUserinfo` | The raw access token — the SDK prepends `Bearer ` itself |
77
+ | `ClientBasicAuth` | `issueTokens`, `introspectToken`, `revokeToken`, `checkSsoEnforcement` | `client_id:client_secret` — the SDK base64-encodes it and prepends `Basic ` |
78
+
79
+ Do **not** prefix the return value with `Bearer ` / `Basic ` yourself; the
80
+ client adds the scheme prefix based on the operation being called. The
81
+ callback receives the scheme descriptor, so a single client can serve both:
82
+
83
+ ```ts
84
+ client.setConfig({
85
+ baseUrl: 'https://your-auth-server.example.com',
86
+ auth: (auth) =>
87
+ auth.scheme === 'basic'
88
+ ? `${process.env.AUTH_CLIENT_ID}:${process.env.AUTH_CLIENT_SECRET}`
89
+ : accessToken,
90
+ });
91
+ ```
92
+
93
+ Access tokens are issued by the Authorization Code + PKCE flow
94
+ (`/oauth/authorize` → `/oauth/token`) and renewed with the `refresh_token`
95
+ grant — see the API reference on the internal portal for the full flow.
96
+ `client_id` / `client_secret` pairs are provisioned per application by the
97
+ Auth Service administrators.
98
+
52
99
  ### Example: fetch the authenticated caller's organization
53
100
 
54
101
  ```ts
@@ -56,7 +103,7 @@ import { client, getMyOrganization } from '@studio-design/studio-auth-node';
56
103
 
57
104
  client.setConfig({
58
105
  baseUrl: 'https://your-auth-server.example.com',
59
- auth: () => `Bearer ${accessToken}`,
106
+ auth: () => accessToken,
60
107
  });
61
108
 
62
109
  try {
@@ -67,21 +114,65 @@ try {
67
114
  // data is typed as `Organization`
68
115
  console.log(data.display_name);
69
116
  } catch (err) {
70
- // With `throwOnError: true`, non-2xx responses throw. The error payload
71
- // follows the RFC 9457 ProblemDetails contract documented in the OpenAPI
72
- // spec (e.g. 403 `membership-required`, 500 `internal-error`).
117
+ // With `throwOnError: true`, non-2xx responses throw.
73
118
  }
74
119
  ```
75
120
 
121
+ ### Error handling
122
+
123
+ By default (without `throwOnError`), operations do not throw on non-2xx
124
+ responses — they return a result object instead:
125
+
126
+ ```ts
127
+ import { getMyOrganization } from '@studio-design/studio-auth-node';
128
+
129
+ const { data, error, response } = await getMyOrganization({
130
+ path: { organization_id: orgId },
131
+ });
132
+
133
+ if (error) {
134
+ // Each operation's `error` is typed (e.g. `GetMyOrganizationError`), so the
135
+ // generated type — not an assumed shape — is the source of truth. Most
136
+ // endpoints return RFC 9457 Problem Details
137
+ // (`type` / `title` / `status` / `detail`), but the OAuth / OIDC endpoints
138
+ // return their own formats on their auth-failure statuses only:
139
+ // `issueTokens` (RFC 6749), `introspectToken` (RFC 7662) and `revokeToken`
140
+ // (RFC 7009) use `{ error, error_description }` on 400/401 (their 429 and
141
+ // 5xx stay Problem Details); `getUserinfo` / `postUserinfo` use RFC 6750 on
142
+ // 401/403; `checkSsoEnforcement` returns its own error object on 401; and the
143
+ // browser-facing flow endpoints redirect (302) on success but render an HTML
144
+ // error page on some statuses — `initiateAuthorization` on 400 (its 422/429
145
+ // are Problem Details), `handleIdpCallback` on 400/403 — while 5xx stays
146
+ // Problem Details.
147
+ //
148
+ // `response` is `undefined` on a network-level failure (fetch threw), where
149
+ // only `error` is set; on an HTTP error response both are present. Read the
150
+ // status as `response?.status` and branch on it with the operation's error type.
151
+ console.error(response?.status, error);
152
+ }
153
+ ```
154
+
155
+ Per-operation error union types (e.g. `GetMyOrganizationError`) and response
156
+ types are exported from the package root.
157
+
76
158
  ## Versioning
77
159
 
78
160
  Releases follow [Semantic Versioning](https://semver.org/). Breaking changes
79
161
  bump the major version; backwards-compatible additions bump the minor version.
80
162
  During the `0.x` series, minor bumps may contain breaking changes.
163
+ See the [CHANGELOG](./CHANGELOG.md) for release history.
81
164
 
82
165
  Published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements/)
83
166
  — verify with `npm audit signatures`.
84
167
 
168
+ ## Contributing
169
+
170
+ This repository is a **read-only release mirror**, generated from the Studio
171
+ Auth Service OpenAPI specification. All files are overwritten on every
172
+ release, so pull requests cannot be accepted here. Bug reports and feature
173
+ requests are welcome via
174
+ [GitHub Issues](https://github.com/studio-design/studio-auth-node/issues).
175
+
85
176
  ## License
86
177
 
87
178
  [MIT](./LICENSE) © Studio Design Inc.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@studio-design/studio-auth-node",
3
- "version": "0.3.2-rc.19",
3
+ "version": "0.3.2-rc.21",
4
4
  "type": "module",
5
5
  "description": "TypeScript SDK for Studio Auth Service API",
6
6
  "license": "MIT",