Component Identity

Some SDK calls accept componentRef to attribute records or subscriptions to an installed WarmHub component — the installable-package concept. A componentRef is the component’s Org/Name ref (for example, acme/locations), the same identifier you pass to wh component install. Component identity is used by component-owned shapes, subscriptions, credentials, and seed data.

Commit Writes

client.commit.apply(...) accepts componentRef in its options object. This is the high-level write entrypoint that carries component identity end-to-end.

await client.commit.apply('acme', 'world', 'install component seed', ops, {
  componentRef: 'acme/locations',
})

OperationBuilder.commit(...) does not accept componentRef today. To attribute a batch to a component, route those call sites through client.commit.apply(...) with componentRef in the options object — build the operations directly as a plain Operation[] rather than through the builder.

The low-level client.stream.append(input) surface also accepts componentRef on the input object — use it only when you already manage stream IDs and allocated tokens directly (for example, installer continuations). Most callers should prefer commit.apply or OperationBuilder.

User tokens can set componentRef for components installed by that user. Tokens with the org:configure scope can claim any installed component in the organization.

Action tokens derive component identity from the running subscription. Explicit mismatches reject with FORBIDDEN.

The CLI wh commit submit command doesn’t currently expose componentRef. The MCP warmhub_commit_submit tool accepts it directly.

Subscriptions

Subscription creation accepts componentRef when the subscription should belong to an installed component.

await client.subscription.create({
  orgName: 'acme',
  repoName: 'world',
  name: 'location-hook',
  kind: 'webhook',
  shapeName: 'Location',
  filterJson: { shape: 'Location' },
  webhookUrl: 'https://example.com/hook',
  componentRef: 'acme/locations',
})

Subscriptions require a filterJson object describing the operations to match, plus a shape binding from either shapeName or filterJson.shape (shape-lifecycle subscriptions instead supply a shape-only filter such as { "kind": "shape" } and omit shapeName). See the WarmHubClient API reference for the full input shape.

The same authority rules apply: installer-owned components are available to that user, tokens with the org:configure scope can claim any installed component in the organization, and action-originated requests derive component identity from their action context.

Related Filters

Read surfaces such as shape and thing listings can filter by component ownership or hide component-owned infrastructure records. See Read Semantics and the WarmHubClient API reference for exact option names.