t4h-framework-amber

name

t4h-framework-amber

description

Documents @t4h.framework/amber (Amber client, Ticket operations, HTTP activities, Basic auth, runtime-claims peers). Use when implementing ticket or protocol flows—integration, creation, updates, transfers, tabulation, comments, locks—or when the user asks about ticket/protocol integration, creating tickets or protocols, or similar; also when they mention @t4h.framework/amber or Amber channel APIs.

@t4h.framework/amber

Amber is the @t4h.framework/amber client for the Amber HTTP API under a tenant + channel base path. Requests use HTTP Basic auth: username = clientId, password = clientSecret.

Source of truth: the @t4h.framework/amber package itself (activity modules, types, tests). If behavior, paths, or payloads are unclear, read those files in the installed package—do not invent URL shapes or field meanings.

Dependencies

Install peers together with this package:

Peer	Role
@t4h.framework/core	History, Claim, AsyncActivity, workflow identifiers.
@t4h.framework/http	AbstractHttpRequestActivity, Response, HttpClientRequestClaim.
@t4h.framework/runtime-claims	GetProjectUniqueIdentifierClaim, GetProjectVersionUniqueIdentifierClaim, GetProjectVersionWorkflowUniqueIdentifierClaim, GetWorkflowUniqueIdentifierClaim, GetActivityUniqueIdentifierClaim (used by activities that need project/workflow context).
typebox	Schemas on async activities (e.g. transfer).

Node: >=22 (see package engines).

URL layout

AmberConfig.url is the API origin (e.g. https://api.example/). The client resolves the channel base as:

v1/tenants/{tenant}/channels/{channel}

(relative to config.url), then stores that string on AmberConnection. All Ticket and Amber calls use this resolved url plus REST segments such as /services, /services/:id, etc., as implemented in each activity.

AmberConfig

Field	Purpose
url	Amber API base URL (origin).
tenant	Tenant id segment in the path (safeTenantId).
channel	Channel id segment; also passed into create payloads.
clientId, clientSecret	Basic auth credentials for every call.

Class: Amber

Constructed with new Amber(config). Exposes:

Method	Purpose
createTicket(input)	POST {url}/services with form body built from input (see AmberCreateTicketActivity). Fills type, channel, metadata (project / version / workflow / run from runtime claims). Returns a Ticket.
getTicket({ id })	GET {url}/services/{id}. Returns a Ticket.

createTicket input type is Omit<AmberCreateTicketActivityInput, 'auth' \| 'url' \| 'channel'> — caller does not pass auth, url, or channel; the Amber class injects them.

Class: Ticket

Returned by createTicket / getTicket. Holds id and connection info; exposes operations that bind the corresponding History activities with auth, url, and id:

Method	HTTP (see activity)
tabulate	POST .../services/{id}/tabulations (JSON body).
transfer	AsyncActivity: metadata PATCH + POST .../services/{id}/transfers (see AmberTransferTicketActivity).
comment	POST .../services/{id}/comments.
interact	POST .../services/{id}/interactions (form body).
update	PATCH .../services/{id}.
finish	update with status: 'finished'.
lock	POST .../services/{id}/locks (JSON includes ref from GetWorkflowUniqueIdentifierClaim).
releaseLock	POST .../services/{id}/locks/current/release.

Note: The package index re-exports Amber and activities; Ticket may not appear in the barrel export *—if you need a named Ticket import, confirm dist/index.d.ts for your version or import from the path your bundler resolves.

AbstractAmberHttpRequestActivity and AmberHttpRequestActivityInput

Most sync flows extend AbstractAmberHttpRequestActivity, which extends AbstractHttpRequestActivity from @t4h.framework/http.

AmberHttpRequestActivityInput = HttpRequestActivityInput & { auth: { username: string; password: string } } (Basic auth is required on Amber requests).

toHttpInput copies url, headers, auth, optional method, body, retry into the generic HTTP activity input.

Exported activities (public API surface)

The package entry exports these activity classes and their *Input types (for advanced / direct History.bind usage):

Activity	Kind	Notes
AmberCreateTicketActivity	Sync HTTP	Uses runtime claims to fill metadata; POST form to /services.
AmberGetTicketActivity	Sync HTTP	GET /services/:id.
AmberUpdateTicketActivity	Sync HTTP	PATCH JSON /services/:id.
AmberCommentTicketActivity	Sync HTTP	POST JSON /services/:id/comments.
AmberInteractTicketActivity	Sync HTTP	POST form /services/:id/interactions.
AmberTabulateTicketActivity	Sync HTTP	POST JSON /services/:id/tabulations.
AmberLockTicketActivity	Sync HTTP	POST JSON /services/:id/locks; ref from claim.
AmberReleaseTicketLockActivity	Sync HTTP	POST JSON /services/:id/locks/current/release.
AmberTransferTicketActivity	AsyncActivity	bootstrap: PATCH metadata, then POST /services/:id/transfers via HttpClientRequestClaim; may pending with TypeBox schema until advance.

Status checks: Several activities expect HTTP 200 and throw Error with cause.httpStatusCode when the status differs.

What to clarify with the user (do not guess)

• Exact Amber base URL, tenant, channel, and credentials for the environment.
• Field semantics for ServiceTicketInput, tabulation, transfer, and interaction payloads (see the Service* type modules in this package).
• Whether Ticket should be a named export from the package (if consumers need import { Ticket }).
• Any activity not listed in src/index.ts is not part of the published public API until added there.

Related plugin skills

• framework-http: generic HttpRequestActivityInput, Response, HttpClientRequestClaim.
• framework-core: History.bind, Claim, AsyncActivity, startWorkflow / StartWorkflowActivity.
• framework-skills-index: map of all framework-* skills.