@camstack/types 1.2.53 → 1.2.54

package/dist/capabilities/oauth-integration.cap.d.ts

@@ -6,6 +6,65 @@ import { type InferProvider } from './capability-definition.js';
  * Each provider returns a static descriptor; the core enumerates them
  * to validate the `integration=` query param and resolve the consent
  * label + the scopes baked into the issued token.
+ *
+ * ## Declaring one
+ *
+ * An OAuth client is integration-specific knowledge — who the client is, what
+ * it may ask for, where it may be sent — so it is declared by the ADDON that
+ * owns the integration, never by the kernel and never as a branch inside
+ * `oauth2-routes.ts` ([D101](../../../../docs/decisions/adr-0101.md)). Three
+ * steps, no others:
+ *
+ * 1. Add `{ "name": "oauth-integration" }` to the addon's `camstack.addons[]`
+ *    manifest entry. This is also what tells the hub, at addon-LOAD time, that
+ *    a descriptor is owed — see "the boot window" below.
+ * 2. Return a provider from `onInitialize()`:
+ *
+ *    ```ts
+ *    const provider: IOauthIntegrationProvider = {
+ *      getDescriptor: async () => ({
+ *        integrationId: 'my-thing',      // the `integration=` query param
+ *        displayName: 'My Thing',
+ *        requestedScopes: [ … ],         // see below
+ *        allowedRedirectPrefixes: ['https://callback.example/'],
+ *      }),
+ *    }
+ *    return [{ capability: oauthIntegrationCapability, provider }]
+ *    ```
+ *
+ *    The descriptor must be **static** — it is read on the authorize path, so
+ *    never put an await on network or disk behind it, and never register it
+ *    behind one either (a provider is registered only once `onInitialize`
+ *    RETURNS, so anything awaited before the return delays linking).
+ * 3. Nothing else. There is no allow-list to join, no id to register with the
+ *    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
+ *    `/api/oauth2/integrations` are built from this collection alone.
+ *
+ * **Scopes.** `requestedScopes` is baked into every token this integration is
+ * ever issued and the operator consents to it once. Derive it from the tRPC
+ * paths the client calls **with that token**, against `METHOD_ACCESS_MAP`, and
+ * prefer a narrow `capability:` scope to a `category:` one unless the client
+ * genuinely needs a whole family. A category scope grants every future member
+ * of that category too. `category:system [create]` has been rejected once and
+ * should stay rejected: it hands `addons.installPackage` to an integration.
+ *
+ * What it does NOT cover: calls the ADDON makes over `ctx.api`, which run as
+ * the addon and are not scope-checked. Alexa's descriptor is narrower than
+ * Home Assistant's for exactly that reason — its Lambda posts directives and
+ * the addon does the work, while the Home Assistant component calls tRPC
+ * directly with the token. So `requestedScopes` describes the blast radius of
+ * the GRANT, not the reach of the integration; do not widen one to describe the
+ * other.
+ *
+ * **The boot window.** An addon registers its provider after its runner forks
+ * and initialises, so between hub start and that moment this collection is
+ * incomplete and an `integrationId` can be legitimately absent. The core does
+ * not wait, poll or cache around this ([D3](../../../../docs/decisions/adr-0003.md)):
+ * it compares the manifest declarers against the registered providers and
+ * answers `503 temporarily_unavailable` (with `Retry-After` and the pending
+ * addon ids) instead of `400 unknown integration`, and reports
+ * `complete: false` on `GET /api/oauth2/integrations`. A client should retry
+ * while the list is incomplete rather than conclude the hub cannot do OAuth.
  */
 declare const OauthIntegrationDescriptorSchema: z.ZodObject<{
     integrationId: z.ZodString;

package/dist/index.js

@@ -13012,6 +13012,65 @@ var ScopedTokenSchema = zod.z.object({
 * Each provider returns a static descriptor; the core enumerates them
 * to validate the `integration=` query param and resolve the consent
 * label + the scopes baked into the issued token.
+*
+* ## Declaring one
+*
+* An OAuth client is integration-specific knowledge — who the client is, what
+* it may ask for, where it may be sent — so it is declared by the ADDON that
+* owns the integration, never by the kernel and never as a branch inside
+* `oauth2-routes.ts` ([D101](../../../../docs/decisions/adr-0101.md)). Three
+* steps, no others:
+*
+* 1. Add `{ "name": "oauth-integration" }` to the addon's `camstack.addons[]`
+*    manifest entry. This is also what tells the hub, at addon-LOAD time, that
+*    a descriptor is owed — see "the boot window" below.
+* 2. Return a provider from `onInitialize()`:
+*
+*    ```ts
+*    const provider: IOauthIntegrationProvider = {
+*      getDescriptor: async () => ({
+*        integrationId: 'my-thing',      // the `integration=` query param
+*        displayName: 'My Thing',
+*        requestedScopes: [ … ],         // see below
+*        allowedRedirectPrefixes: ['https://callback.example/'],
+*      }),
+*    }
+*    return [{ capability: oauthIntegrationCapability, provider }]
+*    ```
+*
+*    The descriptor must be **static** — it is read on the authorize path, so
+*    never put an await on network or disk behind it, and never register it
+*    behind one either (a provider is registered only once `onInitialize`
+*    RETURNS, so anything awaited before the return delays linking).
+* 3. Nothing else. There is no allow-list to join, no id to register with the
+*    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
+*    `/api/oauth2/integrations` are built from this collection alone.
+*
+* **Scopes.** `requestedScopes` is baked into every token this integration is
+* ever issued and the operator consents to it once. Derive it from the tRPC
+* paths the client calls **with that token**, against `METHOD_ACCESS_MAP`, and
+* prefer a narrow `capability:` scope to a `category:` one unless the client
+* genuinely needs a whole family. A category scope grants every future member
+* of that category too. `category:system [create]` has been rejected once and
+* should stay rejected: it hands `addons.installPackage` to an integration.
+*
+* What it does NOT cover: calls the ADDON makes over `ctx.api`, which run as
+* the addon and are not scope-checked. Alexa's descriptor is narrower than
+* Home Assistant's for exactly that reason — its Lambda posts directives and
+* the addon does the work, while the Home Assistant component calls tRPC
+* directly with the token. So `requestedScopes` describes the blast radius of
+* the GRANT, not the reach of the integration; do not widen one to describe the
+* other.
+*
+* **The boot window.** An addon registers its provider after its runner forks
+* and initialises, so between hub start and that moment this collection is
+* incomplete and an `integrationId` can be legitimately absent. The core does
+* not wait, poll or cache around this ([D3](../../../../docs/decisions/adr-0003.md)):
+* it compares the manifest declarers against the registered providers and
+* answers `503 temporarily_unavailable` (with `Retry-After` and the pending
+* addon ids) instead of `400 unknown integration`, and reports
+* `complete: false` on `GET /api/oauth2/integrations`. A client should retry
+* while the list is incomplete rather than conclude the hub cannot do OAuth.
 */
 var OauthIntegrationDescriptorSchema = zod.z.object({
 	/** Stable id used as the `integration=` query param, e.g. 'export-alexa'. */

package/dist/index.mjs

@@ -13011,6 +13011,65 @@ var ScopedTokenSchema = z.object({
 * Each provider returns a static descriptor; the core enumerates them
 * to validate the `integration=` query param and resolve the consent
 * label + the scopes baked into the issued token.
+*
+* ## Declaring one
+*
+* An OAuth client is integration-specific knowledge — who the client is, what
+* it may ask for, where it may be sent — so it is declared by the ADDON that
+* owns the integration, never by the kernel and never as a branch inside
+* `oauth2-routes.ts` ([D101](../../../../docs/decisions/adr-0101.md)). Three
+* steps, no others:
+*
+* 1. Add `{ "name": "oauth-integration" }` to the addon's `camstack.addons[]`
+*    manifest entry. This is also what tells the hub, at addon-LOAD time, that
+*    a descriptor is owed — see "the boot window" below.
+* 2. Return a provider from `onInitialize()`:
+*
+*    ```ts
+*    const provider: IOauthIntegrationProvider = {
+*      getDescriptor: async () => ({
+*        integrationId: 'my-thing',      // the `integration=` query param
+*        displayName: 'My Thing',
+*        requestedScopes: [ … ],         // see below
+*        allowedRedirectPrefixes: ['https://callback.example/'],
+*      }),
+*    }
+*    return [{ capability: oauthIntegrationCapability, provider }]
+*    ```
+*
+*    The descriptor must be **static** — it is read on the authorize path, so
+*    never put an await on network or disk behind it, and never register it
+*    behind one either (a provider is registered only once `onInitialize`
+*    RETURNS, so anything awaited before the return delays linking).
+* 3. Nothing else. There is no allow-list to join, no id to register with the
+*    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
+*    `/api/oauth2/integrations` are built from this collection alone.
+*
+* **Scopes.** `requestedScopes` is baked into every token this integration is
+* ever issued and the operator consents to it once. Derive it from the tRPC
+* paths the client calls **with that token**, against `METHOD_ACCESS_MAP`, and
+* prefer a narrow `capability:` scope to a `category:` one unless the client
+* genuinely needs a whole family. A category scope grants every future member
+* of that category too. `category:system [create]` has been rejected once and
+* should stay rejected: it hands `addons.installPackage` to an integration.
+*
+* What it does NOT cover: calls the ADDON makes over `ctx.api`, which run as
+* the addon and are not scope-checked. Alexa's descriptor is narrower than
+* Home Assistant's for exactly that reason — its Lambda posts directives and
+* the addon does the work, while the Home Assistant component calls tRPC
+* directly with the token. So `requestedScopes` describes the blast radius of
+* the GRANT, not the reach of the integration; do not widen one to describe the
+* other.
+*
+* **The boot window.** An addon registers its provider after its runner forks
+* and initialises, so between hub start and that moment this collection is
+* incomplete and an `integrationId` can be legitimately absent. The core does
+* not wait, poll or cache around this ([D3](../../../../docs/decisions/adr-0003.md)):
+* it compares the manifest declarers against the registered providers and
+* answers `503 temporarily_unavailable` (with `Retry-After` and the pending
+* addon ids) instead of `400 unknown integration`, and reports
+* `complete: false` on `GET /api/oauth2/integrations`. A client should retry
+* while the list is incomplete rather than conclude the hub cannot do OAuth.
 */
 var OauthIntegrationDescriptorSchema = z.object({
 	/** Stable id used as the `integration=` query param, e.g. 'export-alexa'. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.53",
+  "version": "1.2.54",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",