@camstack/develop 0.1.52 → 0.1.53

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.1.53] - 2026-11-12
11
+
12
+ ### Changed
13
+
14
+ - The exporter scaffold implements setExposedName.
15
+
10
16
  ## [0.1.52] - 2026-11-10
11
17
 
12
18
  ### Added
@@ -5,5 +5,5 @@
5
5
  * fields of its own form. Pattern: the Home Assistant export targets.
6
6
  */
7
7
  export declare const EXPORTER_INSTANCES_TS = "/**\n * <%= displayName %> export targets as `integration-instances` (D1009): one `targets` record per\n * target, with a MINTED id (`<%= fileName %>_001`, ...). The devices exported to a target are the\n * `devices` list of ITS record, so deleting the target deletes the exposure and two targets never\n * share one.\n */\nimport {\n type ConfigUISchema,\n defineEntryKind,\n entryBody,\n type IntegrationTestConnectionResult,\n RecordIntegrationInstances,\n type RecordsAccess,\n isInstanceEnabled,\n} from '@camstack/types'\nimport { z } from 'zod'\n\nexport const <%= className %>_TARGET_KIND = '<%= fileName %>-target'\nexport const <%= className %>_ID_PREFIX = '<%= fileName %>_'\n\nexport const <%= className %>TargetsKind = defineEntryKind('targets', {\n title: '<%= displayName %> export targets',\n schema: entryBody({\n endpoint: z.string().optional(),\n token: z.string().optional().meta({ secret: true }),\n devices: z.array(z.string()).optional(),\n /** The target's own switch (D996). Absent means on. */\n enabled: z.boolean().optional(),\n }),\n writeTrigger: 'an operator adds, edits, switches or deletes a target, or exports a device to it',\n})\nexport type <%= className %>TargetBody = z.infer<typeof <%= className %>TargetsKind.schema>\n\n/** Every record kind this addon declares, keyed by its name. */\nexport const <%= className %>RecordKinds = { targets: <%= className %>TargetsKind } as const\n\n/** The next free minted id given the ids that exist (`<%= fileName %>_001`, `<%= fileName %>_002`, ...). */\nexport function next<%= className %>TargetId(existing: Iterable<string>): string {\n let highest = 0\n for (const id of existing) {\n if (!id.startsWith(<%= className %>_ID_PREFIX)) continue\n const n = Number(id.slice(<%= className %>_ID_PREFIX.length))\n if (Number.isInteger(n) && n > highest) highest = n\n }\n return <%= className %>_ID_PREFIX + String(highest + 1).padStart(3, '0')\n}\n\nexport function build<%= className %>TargetForm(addonId: string): ConfigUISchema {\n return {\n sections: [\n {\n id: 'target',\n title: 'Target',\n columns: 1,\n fields: [\n { type: 'text', key: 'name', label: 'Name' },\n { type: 'text', key: 'endpoint', label: 'Endpoint' },\n { type: 'password', key: 'token', label: 'Token', showToggle: true },\n {\n type: 'addon-action-button',\n addonId,\n key: '__resync',\n label: 'Re-announce',\n buttonLabel: 'Push every exposed device now',\n action: 'resync',\n paramsFromForm: { endpoint: 'endpoint' },\n },\n ],\n },\n ],\n }\n}\n\nexport interface <%= className %>TargetDeps {\n /** The ids of the targets that exist now; read per call, a minted id never reuses one. */\n readonly ids: () => readonly string[]\n /** Runs after every change; reload the exposure from the records. */\n readonly onChanged: (id: string) => Promise<void>\n readonly probe: (values: Readonly<Record<string, unknown>>) => Promise<IntegrationTestConnectionResult>\n}\n\nexport function open<%= className %>Targets(\n records: Pick<RecordsAccess, 'kind' | 'owner'>,\n deps: <%= className %>TargetDeps,\n): RecordIntegrationInstances<<%= className %>TargetBody> {\n return new RecordIntegrationInstances<<%= className %>TargetBody>(\n records,\n <%= className %>TargetsKind,\n {\n description: {\n role: 'services',\n instanceMode: 'multiple',\n kind: 'target',\n canTest: true,\n // The one kind this provider serves; kindOf below stamps it on every instance.\n kinds: [{ id: <%= className %>_TARGET_KIND, label: '<%= displayName %>', functionCap: 'device-export', role: 'services' }],\n },\n formSchema: () => build<%= className %>TargetForm('<%= fileName %>'),\n initialBody: (name): <%= className %>TargetBody => ({ name, devices: [] }),\n mintId: () => next<%= className %>TargetId(deps.ids()),\n kindOf: () => <%= className %>_TARGET_KIND,\n // A target without an endpoint is unconfigured: it pushes nothing and KEEPS its devices.\n configured: (body) => (body.endpoint ?? '').length > 0,\n onChanged: (id) => deps.onChanged(id),\n test: ({ values }) => deps.probe(values),\n },\n )\n}\n";
8
- export declare const EXPORTER_ADDON_TS = "/**\n * <%= displayName %> - an exporter (`device-export` + `integration-instances`, D1009). Every\n * exporter is multi-instance: each target is an instance with a minted id, and a membership change\n * ALWAYS names the target it changes. Exposure is the `devices` list of the target's record, keyed\n * by the instance id; an id this addon does not serve is refused by name, never answered empty.\n */\nimport {\n type AddonInitResult,\n BaseAddon,\n customAction,\n defineCustomActions,\n deviceExportCapability,\n deviceExportStatusInstanceOf,\n ExportInstanceUnknownError,\n type IDeviceExportProvider,\n type IntegrationTestConnectionResult,\n integrationInstancesCapability,\n type RecordKindHandle,\n} from '@camstack/types'\nimport { z } from 'zod'\nimport {\n open<%= className %>Targets,\n <%= className %>_TARGET_KIND,\n <%= className %>RecordKinds,\n <%= className %>TargetsKind,\n type <%= className %>TargetBody,\n} from './<%= fileName %>-instances.js'\n\nconst <%= className %>Actions = defineCustomActions({\n resync: customAction(\n z.object({ endpoint: z.string().optional() }),\n z.object({ summary: z.string() }),\n { kind: 'mutation', auth: 'admin' },\n ),\n})\n\n/** The device kinds this exporter can carry; the device picker filters on it. */\nconst SUPPORTED_DEVICE_KINDS: readonly string[] = ['sensor', 'switch', 'light']\n\nexport class <%= className %>Addon extends BaseAddon<Readonly<Record<string, never>>> {\n private targets: RecordKindHandle<<%= className %>TargetBody> | null = null\n /** Target id to its record body; reloaded from the records after every change. */\n private book = new Map<string, <%= className %>TargetBody>()\n\n constructor() {\n super({})\n }\n\n protected override async onInitialize(): Promise<AddonInitResult> {\n const records = this.ctx.records\n if (records === undefined) {\n throw new Error('<%= fileName %>: ctx.records is required (hub-only addon)')\n }\n await records.declare(<%= className %>RecordKinds)\n this.targets = records.kind(<%= className %>TargetsKind)\n const instances = open<%= className %>Targets(records, {\n ids: () => [...this.book.keys()],\n onChanged: () => this.reload(),\n probe: (values) => this.probe(values),\n })\n await this.reload()\n return {\n providers: [\n { capability: deviceExportCapability, provider: this.buildExportProvider() },\n { capability: integrationInstancesCapability, provider: instances.toProvider() },\n ],\n customActions: <%= className %>Actions,\n actionHandlers: {\n resync: async () => {\n await this.reload()\n return { summary: 'Re-announced ' + this.book.size + ' target(s).' }\n },\n },\n }\n }\n\n /** Reload every target from the records; the synchronous read the event path needs. */\n private async reload(): Promise<void> {\n const targets = this.targets\n if (targets === null) return\n const page = await targets.query({ limit: 1000 })\n this.book = new Map(page.records.map((row) => [row.id, row.data]))\n }\n\n /** The body of a target this addon serves, or the named refusal. */\n private target(instanceId: string): <%= className %>TargetBody {\n const body = this.book.get(instanceId)\n if (body === undefined) throw new ExportInstanceUnknownError(this.ctx.id, instanceId)\n return body\n }\n\n private async setMembership(\n instanceId: string,\n deviceId: string,\n exposed: boolean,\n ): Promise<void> {\n const body = this.target(instanceId)\n const current = new Set(body.devices ?? [])\n if (exposed) current.add(deviceId)\n else current.delete(deviceId)\n await this.targets?.patch(instanceId, { devices: [...current] })\n await this.reload()\n }\n\n private buildExportProvider(): IDeviceExportProvider {\n return {\n getStatus: async (input) => {\n const instanceId = deviceExportStatusInstanceOf(input)\n const bodies =\n instanceId === undefined ? [...this.book.values()] : [this.target(instanceId)]\n return {\n linkState: bodies.some((b) => (b.endpoint ?? '').length > 0) ? 'linked' : 'unlinked',\n exposedDeviceCount: new Set(bodies.flatMap((b) => b.devices ?? [])).size,\n }\n },\n listInstances: async () =>\n [...this.book.entries()].map(([instanceId, body]) => ({\n instanceId,\n name: body.name,\n enabled: isInstanceEnabled(body),\n kind: <%= className %>_TARGET_KIND,\n })),\n listSupportedDeviceKinds: async ({ instanceId }) => {\n if (instanceId !== undefined) this.target(instanceId)\n return [...SUPPORTED_DEVICE_KINDS]\n },\n listExposedDevices: async ({ instanceId }) => {\n const bodies =\n instanceId === undefined ? [...this.book.values()] : [this.target(instanceId)]\n return bodies.flatMap((b) => (b.devices ?? []).map((deviceId) => ({ deviceId })))\n },\n exposeDevice: async ({ instanceId, deviceId }) =>\n this.setMembership(instanceId, deviceId, true),\n unexposeDevice: async ({ instanceId, deviceId }) =>\n this.setMembership(instanceId, deviceId, false),\n }\n }\n\n /** Replace with a real call to the remote; `rejected` is a definite no, `inconclusive` is \"could not tell\". */\n private async probe(\n values: Readonly<Record<string, unknown>>,\n ): Promise<IntegrationTestConnectionResult> {\n const endpoint = values['endpoint']\n if (typeof endpoint !== 'string' || endpoint.length === 0) {\n return { success: false, status: 'rejected', error: 'Endpoint is required' }\n }\n return { success: true, status: 'validated' }\n }\n}\n\nexport default <%= className %>Addon\n";
8
+ export declare const EXPORTER_ADDON_TS = "/**\n * <%= displayName %> - an exporter (`device-export` + `integration-instances`, D1009). Every\n * exporter is multi-instance: each target is an instance with a minted id, and a membership change\n * ALWAYS names the target it changes. Exposure is the `devices` list of the target's record, keyed\n * by the instance id; an id this addon does not serve is refused by name, never answered empty.\n */\nimport {\n type AddonInitResult,\n BaseAddon,\n customAction,\n defineCustomActions,\n deviceExportCapability,\n deviceExportStatusInstanceOf,\n ExportInstanceUnknownError,\n exposedNameStoreOf,\n freeTextNameValidator,\n type IDeviceExportProvider,\n type IntegrationTestConnectionResult,\n integrationInstancesCapability,\n type RecordKindHandle,\n saveExposedName,\n} from '@camstack/types'\nimport { z } from 'zod'\nimport {\n open<%= className %>Targets,\n <%= className %>_TARGET_KIND,\n <%= className %>RecordKinds,\n <%= className %>TargetsKind,\n type <%= className %>TargetBody,\n} from './<%= fileName %>-instances.js'\n\nconst <%= className %>Actions = defineCustomActions({\n resync: customAction(\n z.object({ endpoint: z.string().optional() }),\n z.object({ summary: z.string() }),\n { kind: 'mutation', auth: 'admin' },\n ),\n})\n\n/** The device kinds this exporter can carry; the device picker filters on it. */\nconst SUPPORTED_DEVICE_KINDS: readonly string[] = ['sensor', 'switch', 'light']\n\nexport class <%= className %>Addon extends BaseAddon<Readonly<Record<string, never>>> {\n private targets: RecordKindHandle<<%= className %>TargetBody> | null = null\n /** Target id to its record body; reloaded from the records after every change. */\n private book = new Map<string, <%= className %>TargetBody>()\n\n constructor() {\n super({})\n }\n\n protected override async onInitialize(): Promise<AddonInitResult> {\n const records = this.ctx.records\n if (records === undefined) {\n throw new Error('<%= fileName %>: ctx.records is required (hub-only addon)')\n }\n await records.declare(<%= className %>RecordKinds)\n this.targets = records.kind(<%= className %>TargetsKind)\n const instances = open<%= className %>Targets(records, {\n ids: () => [...this.book.keys()],\n onChanged: () => this.reload(),\n probe: (values) => this.probe(values),\n })\n await this.reload()\n return {\n providers: [\n { capability: deviceExportCapability, provider: this.buildExportProvider() },\n { capability: integrationInstancesCapability, provider: instances.toProvider() },\n ],\n customActions: <%= className %>Actions,\n actionHandlers: {\n resync: async () => {\n await this.reload()\n return { summary: 'Re-announced ' + this.book.size + ' target(s).' }\n },\n },\n }\n }\n\n /** Reload every target from the records; the synchronous read the event path needs. */\n private async reload(): Promise<void> {\n const targets = this.targets\n if (targets === null) return\n const page = await targets.query({ limit: 1000 })\n this.book = new Map(page.records.map((row) => [row.id, row.data]))\n }\n\n /** The body of a target this addon serves, or the named refusal. */\n private target(instanceId: string): <%= className %>TargetBody {\n const body = this.book.get(instanceId)\n if (body === undefined) throw new ExportInstanceUnknownError(this.ctx.id, instanceId)\n return body\n }\n\n private async setMembership(\n instanceId: string,\n deviceId: string,\n exposed: boolean,\n ): Promise<void> {\n const body = this.target(instanceId)\n const current = new Set(body.devices ?? [])\n if (exposed) current.add(deviceId)\n else current.delete(deviceId)\n await this.targets?.patch(instanceId, { devices: [...current] })\n await this.reload()\n }\n\n private buildExportProvider(): IDeviceExportProvider {\n return {\n getStatus: async (input) => {\n const instanceId = deviceExportStatusInstanceOf(input)\n const bodies =\n instanceId === undefined ? [...this.book.values()] : [this.target(instanceId)]\n return {\n linkState: bodies.some((b) => (b.endpoint ?? '').length > 0) ? 'linked' : 'unlinked',\n exposedDeviceCount: new Set(bodies.flatMap((b) => b.devices ?? [])).size,\n }\n },\n listInstances: async () =>\n [...this.book.entries()].map(([instanceId, body]) => ({\n instanceId,\n name: body.name,\n enabled: isInstanceEnabled(body),\n kind: <%= className %>_TARGET_KIND,\n })),\n listSupportedDeviceKinds: async ({ instanceId }) => {\n if (instanceId !== undefined) this.target(instanceId)\n return [...SUPPORTED_DEVICE_KINDS]\n },\n listExposedDevices: async ({ instanceId }) => {\n const bodies =\n instanceId === undefined ? [...this.book.values()] : [this.target(instanceId)]\n return bodies.flatMap((b) => (b.devices ?? []).map((deviceId) => ({ deviceId })))\n },\n exposeDevice: async ({ instanceId, deviceId }) =>\n this.setMembership(instanceId, deviceId, true),\n unexposeDevice: async ({ instanceId, deviceId }) =>\n this.setMembership(instanceId, deviceId, false),\n // The device's name on this target (D1049): stored per instance in this addon's per-device\n // store, never part of the exported id. Replace the validator with the platform's rule.\n setExposedName: async ({ instanceId, deviceId, name }) => {\n this.target(instanceId)\n await saveExposedName({\n store: exposedNameStoreOf(this.ctx.settings, this.ctx.id),\n deviceId: Number(deviceId),\n instanceId,\n raw: name,\n validate: freeTextNameValidator('<%= displayName %>', 100),\n })\n },\n }\n }\n\n /** Replace with a real call to the remote; `rejected` is a definite no, `inconclusive` is \"could not tell\". */\n private async probe(\n values: Readonly<Record<string, unknown>>,\n ): Promise<IntegrationTestConnectionResult> {\n const endpoint = values['endpoint']\n if (typeof endpoint !== 'string' || endpoint.length === 0) {\n return { success: false, status: 'rejected', error: 'Endpoint is required' }\n }\n return { success: true, status: 'validated' }\n }\n}\n\nexport default <%= className %>Addon\n";
9
9
  //# sourceMappingURL=integration-exporter.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"integration-exporter.d.ts","sourceRoot":"","sources":["../../src/scaffold/integration-exporter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,qBAAqB,wxIA4GjC,CAAA;AAED,eAAO,MAAM,iBAAiB,mrLAuJ7B,CAAA"}
1
+ {"version":3,"file":"integration-exporter.d.ts","sourceRoot":"","sources":["../../src/scaffold/integration-exporter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,qBAAqB,wxIA4GjC,CAAA;AAED,eAAO,MAAM,iBAAiB,uzMAsK7B,CAAA"}
@@ -127,10 +127,13 @@ import {
127
127
  deviceExportCapability,
128
128
  deviceExportStatusInstanceOf,
129
129
  ExportInstanceUnknownError,
130
+ exposedNameStoreOf,
131
+ freeTextNameValidator,
130
132
  type IDeviceExportProvider,
131
133
  type IntegrationTestConnectionResult,
132
134
  integrationInstancesCapability,
133
135
  type RecordKindHandle,
136
+ saveExposedName,
134
137
  } from '@camstack/types'
135
138
  import { z } from 'zod'
136
139
  import {
@@ -248,6 +251,18 @@ export class <%= className %>Addon extends BaseAddon<Readonly<Record<string, nev
248
251
  this.setMembership(instanceId, deviceId, true),
249
252
  unexposeDevice: async ({ instanceId, deviceId }) =>
250
253
  this.setMembership(instanceId, deviceId, false),
254
+ // The device's name on this target (D1049): stored per instance in this addon's per-device
255
+ // store, never part of the exported id. Replace the validator with the platform's rule.
256
+ setExposedName: async ({ instanceId, deviceId, name }) => {
257
+ this.target(instanceId)
258
+ await saveExposedName({
259
+ store: exposedNameStoreOf(this.ctx.settings, this.ctx.id),
260
+ deviceId: Number(deviceId),
261
+ instanceId,
262
+ raw: name,
263
+ validate: freeTextNameValidator('<%= displayName %>', 100),
264
+ })
265
+ },
251
266
  }
252
267
  }
253
268
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@camstack/develop",
3
- "version": "0.1.52",
3
+ "version": "0.1.53",
4
4
  "description": "CamStack developer tooling — catalogue, scaffold, validate, and example lookup shared by the CLI and MCP server.",
5
5
  "keywords": [
6
6
  "camstack",