@camstack/addon-provider-petkit 0.2.10 → 0.2.11

package/dist/addon.js

@@ -1101,7 +1101,7 @@ var Nodepetkit = class {
 	}
 };
 //#endregion
-//#region ../types/dist/event-category-41fKf-q9.mjs
+//#region ../types/dist/event-category-Cv9dO26A.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -1117,6 +1117,13 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["SystemRestartCompleted"] = "system.restart-completed";
 	/**
+	* A newer addon or server-root package version was found by the
+	* authoritative registry check. Emitted once per
+	* `(target, packageName, currentVersion, latestVersion)` transition; repeated
+	* polling of the same result is deduplicated by the checker.
+	*/
+	EventCategory["UpdateAvailable"] = "update.available";
+	/**
 	* Readiness transition for a capability provider. Every producer emits
 	* this event on `onInitialize` completion, `onDestroy`, and
 	* `$node.reconnect`; every consumer that needs to gate on a cross-process
@@ -15171,8 +15178,35 @@ var NcDeliverySchema = _enum([
 	"immediate",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
+]);
+/**
+* Stable Notification Center vocabulary over infrastructure/liveness events.
+* Bus categories are normalized into these intent-level kinds so rules do not
+* depend on a provider's raw event name or payload shape.
+*/
+var NcSystemEventKindSchema = _enum([
+	"camera-online",
+	"camera-offline",
+	"stream-online",
+	"stream-offline",
+	"node-online",
+	"node-offline",
+	"addon-update-available",
+	"server-update-available"
 ]);
+/**
+* One coherent system-event condition. `kinds` is the required opt-in safety
+* gate; the remaining lists are optional narrowing filters relevant to the
+* selected kinds.
+*/
+var NcSystemEventConditionSchema = object({
+	kinds: array(NcSystemEventKindSchema).min(1),
+	deviceIds: array(number().int()).min(1).optional(),
+	nodeIds: array(string().min(1)).min(1).optional(),
+	packageNames: array(string().min(1)).min(1).optional()
+});
 /** Weekly schedule — OR of windows; absence on the rule = always active. */
 var NcScheduleSchema = object({
 	windows: array(object({
@@ -15477,6 +15511,8 @@ var NcConditionsSchema = object({
 		"picked-up",
 		"both"
 	]).optional(),
+	/** Infrastructure/liveness/update event matcher (`system-event` delivery). */
+	systemEvent: NcSystemEventConditionSchema.optional(),
 	/**
 	* PERSONAL-RULE custom zones (viewer-drawn). Inline normalized polygons
 	* (MaskShape vocabulary). A record passes when its bbox overlaps ANY
@@ -15696,7 +15732,8 @@ var NcTestResultSchema = object({
 		"object-event",
 		"track",
 		"device-event",
-		"package-event"
+		"package-event",
+		"system-event"
 	]),
 	deviceId: number(),
 	timestamp: number(),
@@ -15718,7 +15755,8 @@ var NcConditionDescriptorSchema = object({
 		"schedule",
 		"device",
 		"package",
-		"occupancy"
+		"occupancy",
+		"system"
 	]),
 	label: string(),
 	/** Editor widget the UI renders — never hardcode per-condition forms. */
@@ -15736,7 +15774,8 @@ var NcConditionDescriptorSchema = object({
 		"crossingSelect",
 		"polygonDraw",
 		"occupancy",
-		"deviceState"
+		"deviceState",
+		"systemEvent"
 	]),
 	operator: _enum([
 		"in",
@@ -15795,7 +15834,8 @@ var NcHistoryRecordKindSchema = _enum([
 	"object-event",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
 ]);
 /** Subject summary frozen on the row at fire time (survives rule/record edits). */
 var NcHistorySubjectSchema = object({
@@ -15803,7 +15843,14 @@ var NcHistorySubjectSchema = object({
 	label: string().optional(),
 	confidence: number().optional(),
 	zones: array(string()),
-	timestamp: number()
+	timestamp: number(),
+	systemEvent: object({
+		kind: NcSystemEventKindSchema,
+		subject: string(),
+		title: string(),
+		body: string(),
+		data: record(string(), unknown())
+	}).optional()
 });
 /**
 * One delivery-history row. This is a read-only VIEW over the durable
@@ -16163,6 +16210,76 @@ 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` has exactly ONE meaning: what the integration
+* NEEDS to function.** Not a blast radius, not a conservative
+* under-declaration, not a description of some other path the addon happens to
+* have. Derive it from what the client actually calls **with this token** —
+* every tRPC path against `METHOD_ACCESS_MAP`, plus an `addon:` grant for every
+* addon HTTP route it posts to — and write the call that justifies each entry
+* next to it. Two integrations once used this field to mean two different
+* things; the operator ruled there is one meaning, and any third integration
+* inherits it (2026-08-09).
+*
+* This is not documentation, it is the ENFORCEMENT INPUT. Since
+* [D103](../../../../docs/decisions/adr-0103.md) the `/addon/:addonId/*` gate
+* checks an integration token's grant before letting it reach an
+* `access: 'authenticated'` route, so an **under-declaration is an integration
+* that stops working** — a missing `addon:` entry means `403 Token scope
+* mismatch` on every control the client tries to actuate. Widen the descriptor
+* honestly rather than weakening a check to make a route pass.
+*
+* 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.
+*
+* Calls the ADDON itself makes over `ctx.api` run as the addon and are not
+* scope-checked, so they are not what this field describes — but reaching the
+* addon's route in the first place IS, and that is the entry to declare.
+*
+* **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 = object({
 	/** Stable id used as the `integration=` query param, e.g. 'export-alexa'. */
@@ -16193,7 +16310,30 @@ var OauthIntegrationDescriptorSchema = object({
 	*  present, /api/oauth2/authorize bakes THIS into the code instead of the
 	*  hub-global `publicHubUrl()`, so a forked exporter addon (which can't set
 	*  the hub's env) drives the claim that its cloud Lambda routes back on. */
-	hubUrl: string().optional()
+	hubUrl: string().optional(),
+	/**
+	* How long a REFRESH token issued for this integration lives — seconds, or
+	* `'never'` for a token minted with no `exp` claim at all. Omit to keep the
+	* 30-day default, which is what every link used before this field existed.
+	*
+	* Declared here for the same reason `requestedScopes` is: the integration
+	* knows what it needs. Amazon's account linking and a Home Assistant config
+	* entry are both meant to survive indefinitely, and re-linking is a manual
+	* user action, so a 30-day expiry silently unlinks a working integration.
+	*
+	* **The security posture, stated so it is owned deliberately.** A refresh
+	* token that never expires is permanent access if it leaks. What bounds it is
+	* revocation, not time: `oauthRefresh` re-reads the session on every use and
+	* returns `null` once `revokedAt` is set, as does `oauthVerifyAccessToken`.
+	* The one gap is the ACCESS token — it is a plain signed JWT that nothing
+	* re-checks against the session on the `/trpc` and `/addon/*` paths, so
+	* revoking a link takes effect there only after its remaining hour. That hour
+	* is why the access TTL is not configurable.
+	*
+	* The value is baked into the authorization code at `/authorize` and travels
+	* on the tokens, so editing this field changes FUTURE links only.
+	*/
+	refreshTokenTtlSec: union([number().int().positive(), literal("never")]).optional()
 });
 method(_void(), OauthIntegrationDescriptorSchema);
 /**
@@ -19330,11 +19470,29 @@ var SsoBridgeClaimsSchema = object({
 	codeChallenge: string().optional(),
 	/** OAuth session registry id — set on `oauth-access`/`oauth-refresh`
 	*  tokens so the verify path can check the session is not revoked. */
-	sessionId: string().optional()
+	sessionId: string().optional(),
+	/**
+	* The refresh lifetime this LINK was created with, in seconds, or `'never'`.
+	* Baked into the code at `/authorize` from the integration's descriptor and
+	* carried forward so `oauthRefresh` re-mints with the same lifetime. It rides
+	* on the token rather than being re-read from the descriptor on purpose:
+	* editing a descriptor must not retroactively extend or shorten a link the
+	* operator already consented to.
+	*/
+	refreshTtl: union([number().int().positive(), literal("never")]).optional()
 });
 method(object({
 	claims: SsoBridgeClaimsSchema,
-	ttlSec: number().int().positive().optional()
+	/**
+	* Seconds, or `'never'` for a token minted with NO `exp` claim.
+	*
+	* `'never'` is a literal rather than `undefined`/`0` because omitting
+	* this field already means "the 5-minute SSO hand-off default", and
+	* `jwt.sign` THROWS on `{ expiresIn: undefined }` — a "no expiry" that
+	* went through the numeric path would fail at mint time and break
+	* linking rather than produce an eternal token.
+	*/
+	ttlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ token: string() })), method(object({ token: string() }), SsoBridgeClaimsSchema.nullable());
 var ProviderListEntrySchema = discriminatedUnion("shouldSaveDiskSpace", [object({
 	providerId: string().min(1),
@@ -26534,7 +26692,12 @@ method(_void(), array(UserSummarySchema), { auth: "admin" }), method(CreateUserI
 	hubUrl: string(),
 	/** PKCE (RFC 7636) S256 challenge. Baked into the signed code; a code
 	*  that carries one can ONLY be exchanged with the matching verifier. */
-	codeChallenge: string().optional()
+	codeChallenge: string().optional(),
+	/** The integration's declared refresh lifetime — seconds, or `'never'`.
+	*  From `OauthIntegrationDescriptor.refreshTokenTtlSec`. Baked into the
+	*  code so the link carries its own lifetime; omit for the 30-day
+	*  default. */
+	refreshTtlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ code: string() }), {
 	kind: "mutation",
 	access: "create"

package/dist/addon.mjs

@@ -1100,7 +1100,7 @@ var Nodepetkit = class {
 	}
 };
 //#endregion
-//#region ../types/dist/event-category-41fKf-q9.mjs
+//#region ../types/dist/event-category-Cv9dO26A.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -1116,6 +1116,13 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["SystemRestartCompleted"] = "system.restart-completed";
 	/**
+	* A newer addon or server-root package version was found by the
+	* authoritative registry check. Emitted once per
+	* `(target, packageName, currentVersion, latestVersion)` transition; repeated
+	* polling of the same result is deduplicated by the checker.
+	*/
+	EventCategory["UpdateAvailable"] = "update.available";
+	/**
 	* Readiness transition for a capability provider. Every producer emits
 	* this event on `onInitialize` completion, `onDestroy`, and
 	* `$node.reconnect`; every consumer that needs to gate on a cross-process
@@ -15170,8 +15177,35 @@ var NcDeliverySchema = _enum([
 	"immediate",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
+]);
+/**
+* Stable Notification Center vocabulary over infrastructure/liveness events.
+* Bus categories are normalized into these intent-level kinds so rules do not
+* depend on a provider's raw event name or payload shape.
+*/
+var NcSystemEventKindSchema = _enum([
+	"camera-online",
+	"camera-offline",
+	"stream-online",
+	"stream-offline",
+	"node-online",
+	"node-offline",
+	"addon-update-available",
+	"server-update-available"
 ]);
+/**
+* One coherent system-event condition. `kinds` is the required opt-in safety
+* gate; the remaining lists are optional narrowing filters relevant to the
+* selected kinds.
+*/
+var NcSystemEventConditionSchema = object({
+	kinds: array(NcSystemEventKindSchema).min(1),
+	deviceIds: array(number().int()).min(1).optional(),
+	nodeIds: array(string().min(1)).min(1).optional(),
+	packageNames: array(string().min(1)).min(1).optional()
+});
 /** Weekly schedule — OR of windows; absence on the rule = always active. */
 var NcScheduleSchema = object({
 	windows: array(object({
@@ -15476,6 +15510,8 @@ var NcConditionsSchema = object({
 		"picked-up",
 		"both"
 	]).optional(),
+	/** Infrastructure/liveness/update event matcher (`system-event` delivery). */
+	systemEvent: NcSystemEventConditionSchema.optional(),
 	/**
 	* PERSONAL-RULE custom zones (viewer-drawn). Inline normalized polygons
 	* (MaskShape vocabulary). A record passes when its bbox overlaps ANY
@@ -15695,7 +15731,8 @@ var NcTestResultSchema = object({
 		"object-event",
 		"track",
 		"device-event",
-		"package-event"
+		"package-event",
+		"system-event"
 	]),
 	deviceId: number(),
 	timestamp: number(),
@@ -15717,7 +15754,8 @@ var NcConditionDescriptorSchema = object({
 		"schedule",
 		"device",
 		"package",
-		"occupancy"
+		"occupancy",
+		"system"
 	]),
 	label: string(),
 	/** Editor widget the UI renders — never hardcode per-condition forms. */
@@ -15735,7 +15773,8 @@ var NcConditionDescriptorSchema = object({
 		"crossingSelect",
 		"polygonDraw",
 		"occupancy",
-		"deviceState"
+		"deviceState",
+		"systemEvent"
 	]),
 	operator: _enum([
 		"in",
@@ -15794,7 +15833,8 @@ var NcHistoryRecordKindSchema = _enum([
 	"object-event",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
 ]);
 /** Subject summary frozen on the row at fire time (survives rule/record edits). */
 var NcHistorySubjectSchema = object({
@@ -15802,7 +15842,14 @@ var NcHistorySubjectSchema = object({
 	label: string().optional(),
 	confidence: number().optional(),
 	zones: array(string()),
-	timestamp: number()
+	timestamp: number(),
+	systemEvent: object({
+		kind: NcSystemEventKindSchema,
+		subject: string(),
+		title: string(),
+		body: string(),
+		data: record(string(), unknown())
+	}).optional()
 });
 /**
 * One delivery-history row. This is a read-only VIEW over the durable
@@ -16162,6 +16209,76 @@ 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` has exactly ONE meaning: what the integration
+* NEEDS to function.** Not a blast radius, not a conservative
+* under-declaration, not a description of some other path the addon happens to
+* have. Derive it from what the client actually calls **with this token** —
+* every tRPC path against `METHOD_ACCESS_MAP`, plus an `addon:` grant for every
+* addon HTTP route it posts to — and write the call that justifies each entry
+* next to it. Two integrations once used this field to mean two different
+* things; the operator ruled there is one meaning, and any third integration
+* inherits it (2026-08-09).
+*
+* This is not documentation, it is the ENFORCEMENT INPUT. Since
+* [D103](../../../../docs/decisions/adr-0103.md) the `/addon/:addonId/*` gate
+* checks an integration token's grant before letting it reach an
+* `access: 'authenticated'` route, so an **under-declaration is an integration
+* that stops working** — a missing `addon:` entry means `403 Token scope
+* mismatch` on every control the client tries to actuate. Widen the descriptor
+* honestly rather than weakening a check to make a route pass.
+*
+* 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.
+*
+* Calls the ADDON itself makes over `ctx.api` run as the addon and are not
+* scope-checked, so they are not what this field describes — but reaching the
+* addon's route in the first place IS, and that is the entry to declare.
+*
+* **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 = object({
 	/** Stable id used as the `integration=` query param, e.g. 'export-alexa'. */
@@ -16192,7 +16309,30 @@ var OauthIntegrationDescriptorSchema = object({
 	*  present, /api/oauth2/authorize bakes THIS into the code instead of the
 	*  hub-global `publicHubUrl()`, so a forked exporter addon (which can't set
 	*  the hub's env) drives the claim that its cloud Lambda routes back on. */
-	hubUrl: string().optional()
+	hubUrl: string().optional(),
+	/**
+	* How long a REFRESH token issued for this integration lives — seconds, or
+	* `'never'` for a token minted with no `exp` claim at all. Omit to keep the
+	* 30-day default, which is what every link used before this field existed.
+	*
+	* Declared here for the same reason `requestedScopes` is: the integration
+	* knows what it needs. Amazon's account linking and a Home Assistant config
+	* entry are both meant to survive indefinitely, and re-linking is a manual
+	* user action, so a 30-day expiry silently unlinks a working integration.
+	*
+	* **The security posture, stated so it is owned deliberately.** A refresh
+	* token that never expires is permanent access if it leaks. What bounds it is
+	* revocation, not time: `oauthRefresh` re-reads the session on every use and
+	* returns `null` once `revokedAt` is set, as does `oauthVerifyAccessToken`.
+	* The one gap is the ACCESS token — it is a plain signed JWT that nothing
+	* re-checks against the session on the `/trpc` and `/addon/*` paths, so
+	* revoking a link takes effect there only after its remaining hour. That hour
+	* is why the access TTL is not configurable.
+	*
+	* The value is baked into the authorization code at `/authorize` and travels
+	* on the tokens, so editing this field changes FUTURE links only.
+	*/
+	refreshTokenTtlSec: union([number().int().positive(), literal("never")]).optional()
 });
 method(_void(), OauthIntegrationDescriptorSchema);
 /**
@@ -19329,11 +19469,29 @@ var SsoBridgeClaimsSchema = object({
 	codeChallenge: string().optional(),
 	/** OAuth session registry id — set on `oauth-access`/`oauth-refresh`
 	*  tokens so the verify path can check the session is not revoked. */
-	sessionId: string().optional()
+	sessionId: string().optional(),
+	/**
+	* The refresh lifetime this LINK was created with, in seconds, or `'never'`.
+	* Baked into the code at `/authorize` from the integration's descriptor and
+	* carried forward so `oauthRefresh` re-mints with the same lifetime. It rides
+	* on the token rather than being re-read from the descriptor on purpose:
+	* editing a descriptor must not retroactively extend or shorten a link the
+	* operator already consented to.
+	*/
+	refreshTtl: union([number().int().positive(), literal("never")]).optional()
 });
 method(object({
 	claims: SsoBridgeClaimsSchema,
-	ttlSec: number().int().positive().optional()
+	/**
+	* Seconds, or `'never'` for a token minted with NO `exp` claim.
+	*
+	* `'never'` is a literal rather than `undefined`/`0` because omitting
+	* this field already means "the 5-minute SSO hand-off default", and
+	* `jwt.sign` THROWS on `{ expiresIn: undefined }` — a "no expiry" that
+	* went through the numeric path would fail at mint time and break
+	* linking rather than produce an eternal token.
+	*/
+	ttlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ token: string() })), method(object({ token: string() }), SsoBridgeClaimsSchema.nullable());
 var ProviderListEntrySchema = discriminatedUnion("shouldSaveDiskSpace", [object({
 	providerId: string().min(1),
@@ -26533,7 +26691,12 @@ method(_void(), array(UserSummarySchema), { auth: "admin" }), method(CreateUserI
 	hubUrl: string(),
 	/** PKCE (RFC 7636) S256 challenge. Baked into the signed code; a code
 	*  that carries one can ONLY be exchanged with the matching verifier. */
-	codeChallenge: string().optional()
+	codeChallenge: string().optional(),
+	/** The integration's declared refresh lifetime — seconds, or `'never'`.
+	*  From `OauthIntegrationDescriptor.refreshTokenTtlSec`. Baked into the
+	*  code so the link carries its own lifetime; omit for the 30-day
+	*  default. */
+	refreshTtlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ code: string() }), {
 	kind: "mutation",
 	access: "create"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-petkit",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "PetKit smart-feeder device-provider addon for CamStack — wraps the @apocaliss92/nodepetkit PetKit cloud client",
   "keywords": [
     "camstack",