feat: add stable Forward and Managed API operations

CHANGELOG.md

@@ -5,6 +5,16 @@ existing `0.1.0` release; earlier development prereleases are not listed.
 
 ## [Unreleased]
 
+### Added
+
+- Forward Vault Credential updates for secret rotation and metadata merge patches, with automatic retries disabled for write-only updates.
+- Forward Usage aggregation by Identity and Template using hourly `start_at` / `end_at` windows in Asia/Shanghai, with fractional `active_seconds` and multi-ID filters. Legacy timestamp parameters are not exposed.
+- Managed Session cancellation with the lightweight acknowledgement for both active and idle sessions, plus deployment-scoped Run listing and retrieval.
+
+### Changed
+
+- Forward Credential responses now expose `archived_at` and environment-variable `secret_name`. `auth.mcp_server_url` is optional because environment-variable credentials do not have an MCP URL; check for its presence before using it.
+
 ## [0.2.0] - 2026-09-24
 
 ### Added

CONTRIBUTING.md

@@ -34,6 +34,20 @@ npm run docs:check
 
 Never commit `.env.live`, tokens, credentials, generated logs, or test output. Live scenarios must register cleanup immediately after creating a resource.
 
+`npm run test:live` includes Forward hourly Usage, Credential merge patches
+and secret redaction, and Managed Session cancellation before and after sending
+a turn. Managed deployment scenarios cover scoped Run listing/retrieval. Active
+cancellation and scoped Run execution require the corresponding
+`LIVE_ALLOW_WRITE=true` and `LIVE_ALLOW_EXECUTION=true` gates. Use separate
+`LIVE_ENV_FILE` files with matching URL and PAT for CN and Global.
+
+Usage queries the last 24 completed whole hours in Asia/Shanghai in both regions;
+empty pages verify only the collection. A Session may finish before cancellation
+and return HTTP 200 instead of 202; tests record which response occurred. Those
+responses do not prove active cancellation occurred. Cleanup failures remain
+failures; offline replay exercises assertions and cleanup without account
+credentials.
+
 ## API and contract changes
 
 When adding or changing an endpoint:

README.md

@@ -42,7 +42,7 @@ for await (const event of client.sessions.events.list(session.id, { order: 'asc'
 }
 ```
 
-`ForwardClient` covers the Forward API — `templates`, `identities`, `sessions`, `schedules`, `scheduleRuns`, `batches`, `channels`, `channelPairings`, `environments`, `files`, `skills`, `vaults`, `memoryStores` and `models`.
+`ForwardClient` covers the Forward API — `templates`, `identities`, `sessions`, `schedules`, `scheduleRuns`, `batches`, `channels`, `channelPairings`, `environments`, `files`, `skills`, `vaults`, `memoryStores`, `models` and `usage`.
 
 ```ts
 import { ManagedClient } from 'qca-sdk';
@@ -75,6 +75,39 @@ Each client also has its own entry point — `qca-sdk/forward` and `qca-sdk/mana
 import ForwardClient from 'qca-sdk/forward';
 ```
 
+### Usage and cancellation
+
+Forward Usage requires PAT or Admin SAT.
+
+```ts
+for await (const row of forward.usage.listIdentities({
+  start_at: '2026-09-14T09:00:00', end_at: '2026-09-14T12:00:00',
+  identity_ids: ['idn_one', 'idn_two'],
+})) {
+  console.log(row.identity_id, row.active_seconds, row.credits);
+}
+const acknowledgement = await managed.sessions.cancel('sess_one');
+for await (const run of managed.deployments.runs.list({ deployment_id: 'dep_one', limit: 20 })) {
+  console.log(run.id);
+}
+const run = await managed.deployments.runs.retrieve('drun_one', { deployment_id: 'dep_one' });
+```
+
+`usage.listTemplates` accepts the same filters. Bounds are whole hours in
+Asia/Shanghai for CN and Global, with an inclusive start, exclusive end, and a
+maximum 744-hour span. Multi-ID filters accept arrays or comma-separated strings.
+`active_seconds` preserves fractions. Legacy timestamp parameters and
+`duration_seconds` are not exposed.
+
+`forward.vaults.credentials.update('vault_one', 'cred_one', { auth: {...} })`
+rotates write-only secrets; only auth and metadata are patched, omitted fields
+are preserved, and this operation never retries automatically.
+`metadata: null` clears metadata; `metadata: { key: null }` deletes a key.
+
+Session cancellation returns the lightweight `canceling` acknowledgement for
+active (HTTP 202) and idle (HTTP 200) sessions. The global `deploymentRuns` resource
+remains available.
+
 ### Configuration
 
 `pat` accepts a string or a function returning a string or a promise, which is re-resolved before every request attempt — useful for short-lived tokens. A `Credential` object can be supplied instead; `PATCredential.fromEnv()` reads `QODER_PAT`.

docs/api/forward/README.md

@@ -32,6 +32,7 @@
 - [Skills](classes/Skills.md)
 - [SkillVersions](classes/SkillVersions.md)
 - [Templates](classes/Templates.md)
+- [Usage](classes/Usage.md)
 - [VaultCredentials](classes/VaultCredentials.md)
 - [Vaults](classes/Vaults.md)
 
@@ -105,6 +106,7 @@
 - [IdentityStats](interfaces/IdentityStats.md)
 - [IdentityTemplate](interfaces/IdentityTemplate.md)
 - [IdentityUpdateParams](interfaces/IdentityUpdateParams.md)
+- [IdentityUsage](interfaces/IdentityUsage.md)
 - [ImageSource](interfaces/ImageSource.md)
 - [ImageSourceParam](interfaces/ImageSourceParam.md)
 - [MCPServer](interfaces/MCPServer.md)
@@ -202,17 +204,20 @@
 - [TemplateListParams](interfaces/TemplateListParams.md)
 - [TemplateNewParams](interfaces/TemplateNewParams.md)
 - [TemplateUpdateParams](interfaces/TemplateUpdateParams.md)
+- [TemplateUsage](interfaces/TemplateUsage.md)
 - [Tool](interfaces/Tool.md)
 - [ToolConfig](interfaces/ToolConfig.md)
 - [ToolConfigParam](interfaces/ToolConfigParam.md)
 - [ToolOverride](interfaces/ToolOverride.md)
 - [ToolOverrideParam](interfaces/ToolOverrideParam.md)
 - [ToolParam](interfaces/ToolParam.md)
+- [UsageListParams](interfaces/UsageListParams.md)
 - [Vault](interfaces/Vault.md)
 - [VaultCredential](interfaces/VaultCredential.md)
 - [VaultCredentialAuth](interfaces/VaultCredentialAuth.md)
 - [VaultCredentialListParams](interfaces/VaultCredentialListParams.md)
 - [VaultCredentialNewParams](interfaces/VaultCredentialNewParams.md)
+- [VaultCredentialUpdateParams](interfaces/VaultCredentialUpdateParams.md)
 - [VaultListParams](interfaces/VaultListParams.md)
 - [VaultNewParams](interfaces/VaultNewParams.md)
 
@@ -240,6 +245,7 @@
 - [TemplateCreateParams](type-aliases/TemplateCreateParams.md)
 - [VaultCreateParams](type-aliases/VaultCreateParams.md)
 - [VaultCredentialCreateParams](type-aliases/VaultCredentialCreateParams.md)
+- [VaultCredentialUpdateAuth](type-aliases/VaultCredentialUpdateAuth.md)
 
 ## References
 

docs/api/forward/classes/Usage.md

@@ -0,0 +1,83 @@
+[**qca-sdk**](../../README.md)
+
+***
+
+[qca-sdk](../../README.md) / [forward](../README.md) / Usage
+
+# Class: Usage
+
+Identity/Template aggregates over an hourly Asia/Shanghai window. PAT or Admin SAT required.
+
+## Extends
+
+- `APIResource`
+
+## Constructors
+
+### Constructor
+
+> **new Usage**(`_client`): `Usage`
+
+#### Parameters
+
+##### \_client
+
+[`APIClient`](../../index/classes/APIClient.md)
+
+#### Returns
+
+`Usage`
+
+#### Inherited from
+
+`APIResource.constructor`
+
+## Properties
+
+### \_client
+
+> `protected` `readonly` **\_client**: [`APIClient`](../../index/classes/APIClient.md)
+
+#### Inherited from
+
+`APIResource._client`
+
+## Methods
+
+### listIdentities()
+
+> **listIdentities**(`params`, `options?`): [`PagePromise`](../../index/classes/PagePromise.md)\<[`IdentityUsage`](../interfaces/IdentityUsage.md)\>
+
+#### Parameters
+
+##### params
+
+[`UsageListParams`](../interfaces/UsageListParams.md)
+
+##### options?
+
+[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+
+#### Returns
+
+[`PagePromise`](../../index/classes/PagePromise.md)\<[`IdentityUsage`](../interfaces/IdentityUsage.md)\>
+
+***
+
+### listTemplates()
+
+> **listTemplates**(`params`, `options?`): [`PagePromise`](../../index/classes/PagePromise.md)\<[`TemplateUsage`](../interfaces/TemplateUsage.md)\>
+
+#### Parameters
+
+##### params
+
+[`UsageListParams`](../interfaces/UsageListParams.md)
+
+##### options?
+
+[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+
+#### Returns
+
+[`PagePromise`](../../index/classes/PagePromise.md)\<[`TemplateUsage`](../interfaces/TemplateUsage.md)\>

docs/api/forward/classes/VaultCredentials.md

@@ -159,3 +159,33 @@ listVaultCredential
 #### Operation
 
 getVaultCredential
+
+***
+
+### update()
+
+> **update**(`id`, `credID`, `params`, `options?`): [`APIPromise`](../../index/classes/APIPromise.md)\<[`VaultCredential`](../interfaces/VaultCredential.md)\>
+
+Rotate write-only secrets or merge metadata. This operation is never automatically retried.
+
+#### Parameters
+
+##### id
+
+`string`
+
+##### credID
+
+`string`
+
+##### params
+
+[`VaultCredentialUpdateParams`](../interfaces/VaultCredentialUpdateParams.md)
+
+##### options?
+
+[`RequestOptions`](../../index/interfaces/RequestOptions.md)
+
+#### Returns
+
+[`APIPromise`](../../index/classes/APIPromise.md)\<[`VaultCredential`](../interfaces/VaultCredential.md)\>

docs/api/forward/interfaces/IdentityUsage.md

@@ -0,0 +1,37 @@
+[**qca-sdk**](../../README.md)
+
+***
+
+[qca-sdk](../../README.md) / [forward](../README.md) / IdentityUsage
+
+# Interface: IdentityUsage
+
+## Properties
+
+### active\_seconds
+
+> **active\_seconds**: `number`
+
+***
+
+### credits
+
+> **credits**: `number`
+
+***
+
+### identity\_id
+
+> **identity\_id**: `string`
+
+***
+
+### session\_count
+
+> **session\_count**: `number`
+
+***
+
+### type
+
+> **type**: `"identity_usage"`

docs/api/forward/interfaces/TemplateUsage.md

@@ -0,0 +1,43 @@
+[**qca-sdk**](../../README.md)
+
+***
+
+[qca-sdk](../../README.md) / [forward](../README.md) / TemplateUsage
+
+# Interface: TemplateUsage
+
+## Properties
+
+### active\_identities
+
+> **active\_identities**: `number`
+
+***
+
+### active\_seconds
+
+> **active\_seconds**: `number`
+
+***
+
+### credits
+
+> **credits**: `number`
+
+***
+
+### session\_count
+
+> **session\_count**: `number`
+
+***
+
+### template\_id
+
+> **template\_id**: `string`
+
+***
+
+### type
+
+> **type**: `"template_usage"`

docs/api/forward/interfaces/UsageListParams.md

@@ -0,0 +1,67 @@
+[**qca-sdk**](../../README.md)
+
+***
+
+[qca-sdk](../../README.md) / [forward](../README.md) / UsageListParams
+
+# Interface: UsageListParams
+
+Hourly window in Asia/Shanghai, including CN and Global. No legacy timestamp parameters.
+
+## Properties
+
+### after\_id?
+
+> `optional` **after\_id?**: `string`
+
+***
+
+### before\_id?
+
+> `optional` **before\_id?**: `string`
+
+***
+
+### end\_at
+
+> **end\_at**: `string`
+
+Exclusive YYYY-MM-DDTHH:00:00; maximum span 744 hours.
+
+***
+
+### identity\_id?
+
+> `optional` **identity\_id?**: `string`
+
+***
+
+### identity\_ids?
+
+> `optional` **identity\_ids?**: `string` \| `string`[]
+
+***
+
+### limit?
+
+> `optional` **limit?**: `number`
+
+***
+
+### start\_at
+
+> **start\_at**: `string`
+
+Inclusive YYYY-MM-DDTHH:00:00.
+
+***
+
+### template\_id?
+
+> `optional` **template\_id?**: `string`
+
+***
+
+### template\_ids?
+
+> `optional` **template\_ids?**: `string` \| `string`[]