@camstack/develop 0.1.44 → 0.1.46
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 +12 -0
- package/dist/examples/catalogue.d.ts.map +1 -1
- package/dist/examples/catalogue.js +76 -0
- package/dist/examples/find.js +2 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/scaffold/addon.d.ts.map +1 -1
- package/dist/scaffold/addon.js +104 -10
- package/dist/scaffold/extend.js +5 -4
- package/dist/scaffold/integration-device.d.ts +10 -0
- package/dist/scaffold/integration-device.d.ts.map +1 -0
- package/dist/scaffold/integration-device.js +438 -0
- package/dist/scaffold/integration-exporter.d.ts +9 -0
- package/dist/scaffold/integration-exporter.d.ts.map +1 -0
- package/dist/scaffold/integration-exporter.js +264 -0
- package/dist/scaffold/integration-service.d.ts +7 -0
- package/dist/scaffold/integration-service.d.ts.map +1 -0
- package/dist/scaffold/integration-service.js +153 -0
- package/dist/types.d.ts +9 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +16 -1
- package/package.json +1 -1
- package/skills/camstack-addon.md +36 -1
- package/skills/camstack-capability.md +2 -2
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Templates of the `exporter` scaffold (D1009, D996): every exporter is multi-instance. An export
|
|
3
|
+
* target is an integration INSTANCE (role `services`, `instanceMode: 'multiple'`), its id is MINTED,
|
|
4
|
+
* and what is exposed is keyed by that instance id. A target's actions are \`addon-action-button\`
|
|
5
|
+
* fields of its own form. Pattern: the Home Assistant export targets.
|
|
6
|
+
*/
|
|
7
|
+
export const EXPORTER_INSTANCES_TS = `/**
|
|
8
|
+
* <%= displayName %> export targets as \`integration-instances\` (D1009): one \`targets\` record per
|
|
9
|
+
* target, with a MINTED id (\`<%= fileName %>_001\`, ...). The devices exported to a target are the
|
|
10
|
+
* \`devices\` list of ITS record, so deleting the target deletes the exposure and two targets never
|
|
11
|
+
* share one.
|
|
12
|
+
*/
|
|
13
|
+
import {
|
|
14
|
+
type ConfigUISchema,
|
|
15
|
+
defineEntryKind,
|
|
16
|
+
entryBody,
|
|
17
|
+
type IntegrationTestConnectionResult,
|
|
18
|
+
RecordIntegrationInstances,
|
|
19
|
+
type RecordsAccess,
|
|
20
|
+
} from '@camstack/types'
|
|
21
|
+
import { z } from 'zod'
|
|
22
|
+
|
|
23
|
+
export const <%= className %>_TARGET_KIND = '<%= fileName %>-target'
|
|
24
|
+
export const <%= className %>_ID_PREFIX = '<%= fileName %>_'
|
|
25
|
+
|
|
26
|
+
export const <%= className %>TargetsKind = defineEntryKind('targets', {
|
|
27
|
+
title: '<%= displayName %> export targets',
|
|
28
|
+
schema: entryBody({
|
|
29
|
+
endpoint: z.string().optional(),
|
|
30
|
+
token: z.string().optional().meta({ secret: true }),
|
|
31
|
+
devices: z.array(z.string()).optional(),
|
|
32
|
+
/** The target's own switch (D996). Absent means on. */
|
|
33
|
+
enabled: z.boolean().optional(),
|
|
34
|
+
}),
|
|
35
|
+
writeTrigger: 'an operator adds, edits, switches or deletes a target, or exports a device to it',
|
|
36
|
+
})
|
|
37
|
+
export type <%= className %>TargetBody = z.infer<typeof <%= className %>TargetsKind.schema>
|
|
38
|
+
|
|
39
|
+
/** Every record kind this addon declares, keyed by its name. */
|
|
40
|
+
export const <%= className %>RecordKinds = { targets: <%= className %>TargetsKind } as const
|
|
41
|
+
|
|
42
|
+
/** The next free minted id given the ids that exist (\`<%= fileName %>_001\`, \`<%= fileName %>_002\`, ...). */
|
|
43
|
+
export function next<%= className %>TargetId(existing: Iterable<string>): string {
|
|
44
|
+
let highest = 0
|
|
45
|
+
for (const id of existing) {
|
|
46
|
+
if (!id.startsWith(<%= className %>_ID_PREFIX)) continue
|
|
47
|
+
const n = Number(id.slice(<%= className %>_ID_PREFIX.length))
|
|
48
|
+
if (Number.isInteger(n) && n > highest) highest = n
|
|
49
|
+
}
|
|
50
|
+
return <%= className %>_ID_PREFIX + String(highest + 1).padStart(3, '0')
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function build<%= className %>TargetForm(addonId: string): ConfigUISchema {
|
|
54
|
+
return {
|
|
55
|
+
sections: [
|
|
56
|
+
{
|
|
57
|
+
id: 'target',
|
|
58
|
+
title: 'Target',
|
|
59
|
+
columns: 1,
|
|
60
|
+
fields: [
|
|
61
|
+
{ type: 'text', key: 'name', label: 'Name' },
|
|
62
|
+
{ type: 'text', key: 'endpoint', label: 'Endpoint' },
|
|
63
|
+
{ type: 'password', key: 'token', label: 'Token', showToggle: true },
|
|
64
|
+
{
|
|
65
|
+
type: 'addon-action-button',
|
|
66
|
+
addonId,
|
|
67
|
+
key: '__resync',
|
|
68
|
+
label: 'Re-announce',
|
|
69
|
+
buttonLabel: 'Push every exposed device now',
|
|
70
|
+
action: 'resync',
|
|
71
|
+
paramsFromForm: { endpoint: 'endpoint' },
|
|
72
|
+
},
|
|
73
|
+
],
|
|
74
|
+
},
|
|
75
|
+
],
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export interface <%= className %>TargetDeps {
|
|
80
|
+
/** The ids of the targets that exist now; read per call, a minted id never reuses one. */
|
|
81
|
+
readonly ids: () => readonly string[]
|
|
82
|
+
/** Runs after every change; reload the exposure from the records. */
|
|
83
|
+
readonly onChanged: (id: string) => Promise<void>
|
|
84
|
+
readonly probe: (values: Readonly<Record<string, unknown>>) => Promise<IntegrationTestConnectionResult>
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export function open<%= className %>Targets(
|
|
88
|
+
records: Pick<RecordsAccess, 'kind' | 'owner'>,
|
|
89
|
+
deps: <%= className %>TargetDeps,
|
|
90
|
+
): RecordIntegrationInstances<<%= className %>TargetBody> {
|
|
91
|
+
return new RecordIntegrationInstances<<%= className %>TargetBody>(
|
|
92
|
+
records,
|
|
93
|
+
<%= className %>TargetsKind,
|
|
94
|
+
{
|
|
95
|
+
description: {
|
|
96
|
+
role: 'services',
|
|
97
|
+
instanceMode: 'multiple',
|
|
98
|
+
kind: 'target',
|
|
99
|
+
canTest: true,
|
|
100
|
+
},
|
|
101
|
+
formSchema: () => build<%= className %>TargetForm('<%= fileName %>'),
|
|
102
|
+
initialBody: (name): <%= className %>TargetBody => ({ name, devices: [] }),
|
|
103
|
+
mintId: () => next<%= className %>TargetId(deps.ids()),
|
|
104
|
+
kindOf: () => <%= className %>_TARGET_KIND,
|
|
105
|
+
// A target without an endpoint is unconfigured: it pushes nothing and KEEPS its devices.
|
|
106
|
+
configured: (body) => (body.endpoint ?? '').length > 0,
|
|
107
|
+
onChanged: (id) => deps.onChanged(id),
|
|
108
|
+
test: ({ values }) => deps.probe(values),
|
|
109
|
+
},
|
|
110
|
+
)
|
|
111
|
+
}
|
|
112
|
+
`;
|
|
113
|
+
export const EXPORTER_ADDON_TS = `/**
|
|
114
|
+
* <%= displayName %> - an exporter (\`device-export\` + \`integration-instances\`, D1009). Every
|
|
115
|
+
* exporter is multi-instance: each target is an instance with a minted id, and a membership change
|
|
116
|
+
* ALWAYS names the target it changes. Exposure is the \`devices\` list of the target's record, keyed
|
|
117
|
+
* by the instance id; an id this addon does not serve is refused by name, never answered empty.
|
|
118
|
+
*/
|
|
119
|
+
import {
|
|
120
|
+
type AddonInitResult,
|
|
121
|
+
BaseAddon,
|
|
122
|
+
customAction,
|
|
123
|
+
defineCustomActions,
|
|
124
|
+
deviceExportCapability,
|
|
125
|
+
deviceExportStatusInstanceOf,
|
|
126
|
+
ExportInstanceUnknownError,
|
|
127
|
+
type IDeviceExportProvider,
|
|
128
|
+
type IntegrationTestConnectionResult,
|
|
129
|
+
integrationInstancesCapability,
|
|
130
|
+
type RecordKindHandle,
|
|
131
|
+
} from '@camstack/types'
|
|
132
|
+
import { z } from 'zod'
|
|
133
|
+
import {
|
|
134
|
+
open<%= className %>Targets,
|
|
135
|
+
<%= className %>_TARGET_KIND,
|
|
136
|
+
<%= className %>RecordKinds,
|
|
137
|
+
<%= className %>TargetsKind,
|
|
138
|
+
type <%= className %>TargetBody,
|
|
139
|
+
} from './<%= fileName %>-instances.js'
|
|
140
|
+
|
|
141
|
+
const <%= className %>Actions = defineCustomActions({
|
|
142
|
+
resync: customAction(
|
|
143
|
+
z.object({ endpoint: z.string().optional() }),
|
|
144
|
+
z.object({ summary: z.string() }),
|
|
145
|
+
{ kind: 'mutation', auth: 'admin' },
|
|
146
|
+
),
|
|
147
|
+
})
|
|
148
|
+
|
|
149
|
+
/** The device kinds this exporter can carry; the device picker filters on it. */
|
|
150
|
+
const SUPPORTED_DEVICE_KINDS: readonly string[] = ['sensor', 'switch', 'light']
|
|
151
|
+
|
|
152
|
+
export class <%= className %>Addon extends BaseAddon<Readonly<Record<string, never>>> {
|
|
153
|
+
private targets: RecordKindHandle<<%= className %>TargetBody> | null = null
|
|
154
|
+
/** Target id to its record body; reloaded from the records after every change. */
|
|
155
|
+
private book = new Map<string, <%= className %>TargetBody>()
|
|
156
|
+
|
|
157
|
+
constructor() {
|
|
158
|
+
super({})
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
protected override async onInitialize(): Promise<AddonInitResult> {
|
|
162
|
+
const records = this.ctx.records
|
|
163
|
+
if (records === undefined) {
|
|
164
|
+
throw new Error('<%= fileName %>: ctx.records is required (hub-only addon)')
|
|
165
|
+
}
|
|
166
|
+
await records.declare(<%= className %>RecordKinds)
|
|
167
|
+
this.targets = records.kind(<%= className %>TargetsKind)
|
|
168
|
+
const instances = open<%= className %>Targets(records, {
|
|
169
|
+
ids: () => [...this.book.keys()],
|
|
170
|
+
onChanged: () => this.reload(),
|
|
171
|
+
probe: (values) => this.probe(values),
|
|
172
|
+
})
|
|
173
|
+
await this.reload()
|
|
174
|
+
return {
|
|
175
|
+
providers: [
|
|
176
|
+
{ capability: deviceExportCapability, provider: this.buildExportProvider() },
|
|
177
|
+
{ capability: integrationInstancesCapability, provider: instances.toProvider() },
|
|
178
|
+
],
|
|
179
|
+
customActions: <%= className %>Actions,
|
|
180
|
+
actionHandlers: {
|
|
181
|
+
resync: async () => {
|
|
182
|
+
await this.reload()
|
|
183
|
+
return { summary: 'Re-announced ' + this.book.size + ' target(s).' }
|
|
184
|
+
},
|
|
185
|
+
},
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/** Reload every target from the records; the synchronous read the event path needs. */
|
|
190
|
+
private async reload(): Promise<void> {
|
|
191
|
+
const targets = this.targets
|
|
192
|
+
if (targets === null) return
|
|
193
|
+
const page = await targets.query({ limit: 1000 })
|
|
194
|
+
this.book = new Map(page.records.map((row) => [row.id, row.data]))
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/** The body of a target this addon serves, or the named refusal. */
|
|
198
|
+
private target(instanceId: string): <%= className %>TargetBody {
|
|
199
|
+
const body = this.book.get(instanceId)
|
|
200
|
+
if (body === undefined) throw new ExportInstanceUnknownError(this.ctx.id, instanceId)
|
|
201
|
+
return body
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
private async setMembership(
|
|
205
|
+
instanceId: string,
|
|
206
|
+
deviceId: string,
|
|
207
|
+
exposed: boolean,
|
|
208
|
+
): Promise<void> {
|
|
209
|
+
const body = this.target(instanceId)
|
|
210
|
+
const current = new Set(body.devices ?? [])
|
|
211
|
+
if (exposed) current.add(deviceId)
|
|
212
|
+
else current.delete(deviceId)
|
|
213
|
+
await this.targets?.patch(instanceId, { devices: [...current] })
|
|
214
|
+
await this.reload()
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
private buildExportProvider(): IDeviceExportProvider {
|
|
218
|
+
return {
|
|
219
|
+
getStatus: async (input) => {
|
|
220
|
+
const instanceId = deviceExportStatusInstanceOf(input)
|
|
221
|
+
const bodies =
|
|
222
|
+
instanceId === undefined ? [...this.book.values()] : [this.target(instanceId)]
|
|
223
|
+
return {
|
|
224
|
+
linkState: bodies.some((b) => (b.endpoint ?? '').length > 0) ? 'linked' : 'unlinked',
|
|
225
|
+
exposedDeviceCount: new Set(bodies.flatMap((b) => b.devices ?? [])).size,
|
|
226
|
+
}
|
|
227
|
+
},
|
|
228
|
+
listInstances: async () =>
|
|
229
|
+
[...this.book.entries()].map(([instanceId, body]) => ({
|
|
230
|
+
instanceId,
|
|
231
|
+
name: body.name,
|
|
232
|
+
enabled: body.enabled !== false,
|
|
233
|
+
kind: <%= className %>_TARGET_KIND,
|
|
234
|
+
})),
|
|
235
|
+
listSupportedDeviceKinds: async ({ instanceId }) => {
|
|
236
|
+
if (instanceId !== undefined) this.target(instanceId)
|
|
237
|
+
return [...SUPPORTED_DEVICE_KINDS]
|
|
238
|
+
},
|
|
239
|
+
listExposedDevices: async ({ instanceId }) => {
|
|
240
|
+
const bodies =
|
|
241
|
+
instanceId === undefined ? [...this.book.values()] : [this.target(instanceId)]
|
|
242
|
+
return bodies.flatMap((b) => (b.devices ?? []).map((deviceId) => ({ deviceId })))
|
|
243
|
+
},
|
|
244
|
+
exposeDevice: async ({ instanceId, deviceId }) =>
|
|
245
|
+
this.setMembership(instanceId, deviceId, true),
|
|
246
|
+
unexposeDevice: async ({ instanceId, deviceId }) =>
|
|
247
|
+
this.setMembership(instanceId, deviceId, false),
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/** Replace with a real call to the remote; \`rejected\` is a definite no, \`inconclusive\` is "could not tell". */
|
|
252
|
+
private async probe(
|
|
253
|
+
values: Readonly<Record<string, unknown>>,
|
|
254
|
+
): Promise<IntegrationTestConnectionResult> {
|
|
255
|
+
const endpoint = values['endpoint']
|
|
256
|
+
if (typeof endpoint !== 'string' || endpoint.length === 0) {
|
|
257
|
+
return { success: false, status: 'rejected', error: 'Endpoint is required' }
|
|
258
|
+
}
|
|
259
|
+
return { success: true, status: 'validated' }
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
export default <%= className %>Addon
|
|
264
|
+
`;
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Templates of the `service-integration` scaffold (D1007, D996): an addon whose integration is a
|
|
3
|
+
* typed connection plus a secret, with a test, and no devices of its own (role `services`).
|
|
4
|
+
*/
|
|
5
|
+
export declare const SERVICE_INSTANCES_TS = "/**\n * <%= displayName %> integrations as `integration-instances` (D1007): one `connections` record per\n * integration, keyed by the registry id. The API key is a secret by TYPE (`.meta({ secret: true })`),\n * so the records door keeps it in the keychain and deleting the row deletes the secret.\n * There is no addon-level settings page: everything an operator configures is an instance.\n */\nimport {\n type ConfigUISchema,\n defineEntryKind,\n entryBody,\n type IntegrationTestConnectionResult,\n RecordIntegrationInstances,\n type RecordsAccess,\n} from '@camstack/types'\nimport { z } from 'zod'\n\nexport const <%= className %>ConnectionsKind = defineEntryKind('connections', {\n title: '<%= displayName %> integrations',\n schema: entryBody({\n baseUrl: z.string().optional(),\n apiKey: z.string().optional().meta({ secret: true }),\n }),\n writeTrigger: 'an operator adds, edits or removes a <%= displayName %> integration',\n})\nexport type <%= className %>ConnectionBody = z.infer<typeof <%= className %>ConnectionsKind.schema>\n\n/** Every record kind this addon declares, keyed by its name. */\nexport const <%= className %>RecordKinds = { connections: <%= className %>ConnectionsKind } as const\n\nexport function build<%= className %>ConnectionForm(): ConfigUISchema {\n return {\n sections: [\n {\n id: 'connection',\n title: 'Connection',\n columns: 1,\n fields: [\n { type: 'text', key: 'name', label: 'Name' },\n { type: 'text', key: 'baseUrl', label: 'Base URL' },\n { type: 'password', key: 'apiKey', label: 'API key', showToggle: true },\n ],\n },\n ],\n }\n}\n\nexport interface <%= className %>InstanceDeps {\n /** Re-apply the runtime from the records after a create, update, enable or delete. */\n readonly onChanged: () => Promise<void>\n /** Probe the remote with the (possibly unsaved) values; a failed probe is not a pass. */\n readonly probe: (values: Readonly<Record<string, unknown>>) => Promise<IntegrationTestConnectionResult>\n}\n\nexport function build<%= className %>Instances(\n records: Pick<RecordsAccess, 'kind' | 'owner'>,\n deps: <%= className %>InstanceDeps,\n): RecordIntegrationInstances<<%= className %>ConnectionBody> {\n return new RecordIntegrationInstances<<%= className %>ConnectionBody>(\n records,\n <%= className %>ConnectionsKind,\n {\n description: {\n role: 'services',\n instanceMode: 'multiple',\n kind: 'server',\n canTest: true,\n },\n formSchema: () => build<%= className %>ConnectionForm(),\n initialBody: (name): <%= className %>ConnectionBody => ({ name }),\n configured: (body) => (body.baseUrl ?? '').length > 0,\n onChanged: () => deps.onChanged(),\n test: ({ values }) => deps.probe(values),\n },\n )\n}\n";
|
|
6
|
+
export declare const SERVICE_ADDON_TS = "/**\n * <%= displayName %> \u2014 a service integration (role `services`, D996). It brings no devices: an\n * integration is one typed connection record, listed on the Integrations page, with a secret and a\n * Test button. Read the connection per use with `instances.readResolved(id)`; never keep a second\n * copy of it.\n */\nimport {\n type AddonInitResult,\n BaseAddon,\n errMsg,\n type IntegrationTestConnectionResult,\n integrationInstancesCapability,\n type RecordIntegrationInstances,\n} from '@camstack/types'\nimport {\n build<%= className %>Instances,\n <%= className %>RecordKinds,\n type <%= className %>ConnectionBody,\n} from './<%= fileName %>-instances.js'\n\nexport class <%= className %>Addon extends BaseAddon<Readonly<Record<string, never>>> {\n private instances: RecordIntegrationInstances<<%= className %>ConnectionBody> | null = null\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 const instances = build<%= className %>Instances(records, {\n onChanged: () => this.applyInstances(),\n probe: (values) => this.probe(values),\n })\n this.instances = instances\n await this.applyInstances()\n return {\n providers: [\n { capability: integrationInstancesCapability, provider: instances.toProvider() },\n ],\n }\n }\n\n /** Re-apply the runtime from the records; called at boot and after every instance change. */\n private async applyInstances(): Promise<void> {\n const all = (await this.instances?.listResolved()) ?? []\n this.ctx.logger.info('<%= displayName %> integrations applied', {\n meta: { count: all.length },\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 baseUrl = values['baseUrl']\n if (typeof baseUrl !== 'string' || baseUrl.length === 0) {\n return { success: false, status: 'rejected', error: 'Base URL is required' }\n }\n try {\n new URL(baseUrl)\n return { success: true, status: 'validated' }\n } catch (err: unknown) {\n return { success: false, status: 'rejected', error: errMsg(err) }\n }\n }\n}\n\nexport default <%= className %>Addon\n";
|
|
7
|
+
//# sourceMappingURL=integration-service.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"integration-service.d.ts","sourceRoot":"","sources":["../../src/scaffold/integration-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,oBAAoB,+yFA2EhC,CAAA;AAED,eAAO,MAAM,gBAAgB,uiFAwE5B,CAAA"}
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Templates of the `service-integration` scaffold (D1007, D996): an addon whose integration is a
|
|
3
|
+
* typed connection plus a secret, with a test, and no devices of its own (role `services`).
|
|
4
|
+
*/
|
|
5
|
+
export const SERVICE_INSTANCES_TS = `/**
|
|
6
|
+
* <%= displayName %> integrations as \`integration-instances\` (D1007): one \`connections\` record per
|
|
7
|
+
* integration, keyed by the registry id. The API key is a secret by TYPE (\`.meta({ secret: true })\`),
|
|
8
|
+
* so the records door keeps it in the keychain and deleting the row deletes the secret.
|
|
9
|
+
* There is no addon-level settings page: everything an operator configures is an instance.
|
|
10
|
+
*/
|
|
11
|
+
import {
|
|
12
|
+
type ConfigUISchema,
|
|
13
|
+
defineEntryKind,
|
|
14
|
+
entryBody,
|
|
15
|
+
type IntegrationTestConnectionResult,
|
|
16
|
+
RecordIntegrationInstances,
|
|
17
|
+
type RecordsAccess,
|
|
18
|
+
} from '@camstack/types'
|
|
19
|
+
import { z } from 'zod'
|
|
20
|
+
|
|
21
|
+
export const <%= className %>ConnectionsKind = defineEntryKind('connections', {
|
|
22
|
+
title: '<%= displayName %> integrations',
|
|
23
|
+
schema: entryBody({
|
|
24
|
+
baseUrl: z.string().optional(),
|
|
25
|
+
apiKey: z.string().optional().meta({ secret: true }),
|
|
26
|
+
}),
|
|
27
|
+
writeTrigger: 'an operator adds, edits or removes a <%= displayName %> integration',
|
|
28
|
+
})
|
|
29
|
+
export type <%= className %>ConnectionBody = z.infer<typeof <%= className %>ConnectionsKind.schema>
|
|
30
|
+
|
|
31
|
+
/** Every record kind this addon declares, keyed by its name. */
|
|
32
|
+
export const <%= className %>RecordKinds = { connections: <%= className %>ConnectionsKind } as const
|
|
33
|
+
|
|
34
|
+
export function build<%= className %>ConnectionForm(): ConfigUISchema {
|
|
35
|
+
return {
|
|
36
|
+
sections: [
|
|
37
|
+
{
|
|
38
|
+
id: 'connection',
|
|
39
|
+
title: 'Connection',
|
|
40
|
+
columns: 1,
|
|
41
|
+
fields: [
|
|
42
|
+
{ type: 'text', key: 'name', label: 'Name' },
|
|
43
|
+
{ type: 'text', key: 'baseUrl', label: 'Base URL' },
|
|
44
|
+
{ type: 'password', key: 'apiKey', label: 'API key', showToggle: true },
|
|
45
|
+
],
|
|
46
|
+
},
|
|
47
|
+
],
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export interface <%= className %>InstanceDeps {
|
|
52
|
+
/** Re-apply the runtime from the records after a create, update, enable or delete. */
|
|
53
|
+
readonly onChanged: () => Promise<void>
|
|
54
|
+
/** Probe the remote with the (possibly unsaved) values; a failed probe is not a pass. */
|
|
55
|
+
readonly probe: (values: Readonly<Record<string, unknown>>) => Promise<IntegrationTestConnectionResult>
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export function build<%= className %>Instances(
|
|
59
|
+
records: Pick<RecordsAccess, 'kind' | 'owner'>,
|
|
60
|
+
deps: <%= className %>InstanceDeps,
|
|
61
|
+
): RecordIntegrationInstances<<%= className %>ConnectionBody> {
|
|
62
|
+
return new RecordIntegrationInstances<<%= className %>ConnectionBody>(
|
|
63
|
+
records,
|
|
64
|
+
<%= className %>ConnectionsKind,
|
|
65
|
+
{
|
|
66
|
+
description: {
|
|
67
|
+
role: 'services',
|
|
68
|
+
instanceMode: 'multiple',
|
|
69
|
+
kind: 'server',
|
|
70
|
+
canTest: true,
|
|
71
|
+
},
|
|
72
|
+
formSchema: () => build<%= className %>ConnectionForm(),
|
|
73
|
+
initialBody: (name): <%= className %>ConnectionBody => ({ name }),
|
|
74
|
+
configured: (body) => (body.baseUrl ?? '').length > 0,
|
|
75
|
+
onChanged: () => deps.onChanged(),
|
|
76
|
+
test: ({ values }) => deps.probe(values),
|
|
77
|
+
},
|
|
78
|
+
)
|
|
79
|
+
}
|
|
80
|
+
`;
|
|
81
|
+
export const SERVICE_ADDON_TS = `/**
|
|
82
|
+
* <%= displayName %> — a service integration (role \`services\`, D996). It brings no devices: an
|
|
83
|
+
* integration is one typed connection record, listed on the Integrations page, with a secret and a
|
|
84
|
+
* Test button. Read the connection per use with \`instances.readResolved(id)\`; never keep a second
|
|
85
|
+
* copy of it.
|
|
86
|
+
*/
|
|
87
|
+
import {
|
|
88
|
+
type AddonInitResult,
|
|
89
|
+
BaseAddon,
|
|
90
|
+
errMsg,
|
|
91
|
+
type IntegrationTestConnectionResult,
|
|
92
|
+
integrationInstancesCapability,
|
|
93
|
+
type RecordIntegrationInstances,
|
|
94
|
+
} from '@camstack/types'
|
|
95
|
+
import {
|
|
96
|
+
build<%= className %>Instances,
|
|
97
|
+
<%= className %>RecordKinds,
|
|
98
|
+
type <%= className %>ConnectionBody,
|
|
99
|
+
} from './<%= fileName %>-instances.js'
|
|
100
|
+
|
|
101
|
+
export class <%= className %>Addon extends BaseAddon<Readonly<Record<string, never>>> {
|
|
102
|
+
private instances: RecordIntegrationInstances<<%= className %>ConnectionBody> | null = null
|
|
103
|
+
|
|
104
|
+
constructor() {
|
|
105
|
+
super({})
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
protected override async onInitialize(): Promise<AddonInitResult> {
|
|
109
|
+
const records = this.ctx.records
|
|
110
|
+
if (records === undefined) {
|
|
111
|
+
throw new Error('<%= fileName %>: ctx.records is required (hub-only addon)')
|
|
112
|
+
}
|
|
113
|
+
await records.declare(<%= className %>RecordKinds)
|
|
114
|
+
const instances = build<%= className %>Instances(records, {
|
|
115
|
+
onChanged: () => this.applyInstances(),
|
|
116
|
+
probe: (values) => this.probe(values),
|
|
117
|
+
})
|
|
118
|
+
this.instances = instances
|
|
119
|
+
await this.applyInstances()
|
|
120
|
+
return {
|
|
121
|
+
providers: [
|
|
122
|
+
{ capability: integrationInstancesCapability, provider: instances.toProvider() },
|
|
123
|
+
],
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Re-apply the runtime from the records; called at boot and after every instance change. */
|
|
128
|
+
private async applyInstances(): Promise<void> {
|
|
129
|
+
const all = (await this.instances?.listResolved()) ?? []
|
|
130
|
+
this.ctx.logger.info('<%= displayName %> integrations applied', {
|
|
131
|
+
meta: { count: all.length },
|
|
132
|
+
})
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/** Replace with a real call to the remote; \`rejected\` is a definite no, \`inconclusive\` is "could not tell". */
|
|
136
|
+
private async probe(
|
|
137
|
+
values: Readonly<Record<string, unknown>>,
|
|
138
|
+
): Promise<IntegrationTestConnectionResult> {
|
|
139
|
+
const baseUrl = values['baseUrl']
|
|
140
|
+
if (typeof baseUrl !== 'string' || baseUrl.length === 0) {
|
|
141
|
+
return { success: false, status: 'rejected', error: 'Base URL is required' }
|
|
142
|
+
}
|
|
143
|
+
try {
|
|
144
|
+
new URL(baseUrl)
|
|
145
|
+
return { success: true, status: 'validated' }
|
|
146
|
+
} catch (err: unknown) {
|
|
147
|
+
return { success: false, status: 'rejected', error: errMsg(err) }
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
export default <%= className %>Addon
|
|
153
|
+
`;
|
package/dist/types.d.ts
CHANGED
|
@@ -35,8 +35,11 @@ export interface CapabilitySummary {
|
|
|
35
35
|
}
|
|
36
36
|
export interface ExampleEntry {
|
|
37
37
|
readonly id: string;
|
|
38
|
+
/** Path inside this repository, or inside `repository` when that is set. */
|
|
38
39
|
readonly packageDir: string;
|
|
39
|
-
|
|
40
|
+
/** The public repository holding the example (`owner/name`); absent for an in-repo example. */
|
|
41
|
+
readonly repository?: string;
|
|
42
|
+
readonly kind: 'provider' | 'notifier' | 'osd' | 'post-analysis' | 'model-studio' | 'admin-ui' | 'device-integration' | 'service-integration' | 'exporter' | 'builtin' | 'other';
|
|
40
43
|
readonly demonstrates: string;
|
|
41
44
|
readonly tags: readonly string[];
|
|
42
45
|
}
|
|
@@ -55,6 +58,10 @@ export interface ValidationResult {
|
|
|
55
58
|
readonly ok: boolean;
|
|
56
59
|
readonly findings: readonly ValidationFinding[];
|
|
57
60
|
}
|
|
61
|
+
/** Every template flavour `scaffold_addon` offers. */
|
|
62
|
+
export declare const SCAFFOLD_KINDS: readonly ["empty", "provider", "notifier", "osd", "post-analysis", "model-studio", "admin-ui", "device-integration", "service-integration", "exporter"];
|
|
63
|
+
export type ScaffoldKind = (typeof SCAFFOLD_KINDS)[number];
|
|
64
|
+
export declare function isScaffoldKind(value: string): value is ScaffoldKind;
|
|
58
65
|
export interface ScaffoldAddonOptions {
|
|
59
66
|
readonly workspaceRoot: string;
|
|
60
67
|
readonly name: string;
|
|
@@ -62,7 +69,7 @@ export interface ScaffoldAddonOptions {
|
|
|
62
69
|
readonly description?: string;
|
|
63
70
|
readonly directory?: string;
|
|
64
71
|
/** Template flavour — empty skeleton, or a stub pointing at a core example. */
|
|
65
|
-
readonly kind?:
|
|
72
|
+
readonly kind?: ScaffoldKind;
|
|
66
73
|
readonly dryRun?: boolean;
|
|
67
74
|
}
|
|
68
75
|
export interface ScaffoldAddonResult {
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/dist/types.js
CHANGED
|
@@ -1,2 +1,17 @@
|
|
|
1
1
|
/** Shared result / catalogue shapes for CLI + MCP surfaces. */
|
|
2
|
-
|
|
2
|
+
/** Every template flavour `scaffold_addon` offers. */
|
|
3
|
+
export const SCAFFOLD_KINDS = [
|
|
4
|
+
'empty',
|
|
5
|
+
'provider',
|
|
6
|
+
'notifier',
|
|
7
|
+
'osd',
|
|
8
|
+
'post-analysis',
|
|
9
|
+
'model-studio',
|
|
10
|
+
'admin-ui',
|
|
11
|
+
'device-integration',
|
|
12
|
+
'service-integration',
|
|
13
|
+
'exporter',
|
|
14
|
+
];
|
|
15
|
+
export function isScaffoldKind(value) {
|
|
16
|
+
return SCAFFOLD_KINDS.some((kind) => kind === value);
|
|
17
|
+
}
|
package/package.json
CHANGED
package/skills/camstack-addon.md
CHANGED
|
@@ -17,12 +17,24 @@ crashes) and `docs/architecture/addon-custom-actions.md`.
|
|
|
17
17
|
## Tooling (prefer this over hand-copying)
|
|
18
18
|
|
|
19
19
|
```bash
|
|
20
|
-
camstack develop scaffold addon <name> [--kind empty|provider|notifier|osd|post-analysis]
|
|
20
|
+
camstack develop scaffold addon <name> [--kind empty|provider|notifier|osd|post-analysis|device-integration|service-integration|exporter]
|
|
21
21
|
camstack develop extend <existing-addon> --entry <new-id>
|
|
22
22
|
camstack develop find-example <topic>
|
|
23
23
|
camstack develop validate <name-or-path>
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
+
The three integration kinds start from a typed instance record
|
|
27
|
+
(`RecordIntegrationInstances`): `device-integration` (role `devices`: connection
|
|
28
|
+
+ `password` secret + test, discovery and adoption, the Gateway adopted as a
|
|
29
|
+
SIBLING of the devices, `integrationId` on every device, `device-removal-hook`),
|
|
30
|
+
`service-integration` (role `services`: connection + secret + test, no devices)
|
|
31
|
+
and `exporter` (`device-export` + `integration-instances`, minted ids, exposure
|
|
32
|
+
keyed by instance id, actions as `addon-action-button` in the instance form).
|
|
33
|
+
Real implementations to study: `packages/addon-provider-enpal`,
|
|
34
|
+
`packages/addon-provider-homeassistant/src/ha-export/target-instances.ts`, and
|
|
35
|
+
the public `addon-examples` packages `example-device-integration`,
|
|
36
|
+
`example-service-integration` and `example-exporter`.
|
|
37
|
+
|
|
26
38
|
Nx equivalent (same idea): `nx g @camstack/nx-plugin:addon <name>`.
|
|
27
39
|
The develop scaffold also writes `vite.config.ts` `entries` — the miss that
|
|
28
40
|
fails only at runtime.
|
|
@@ -278,6 +290,29 @@ row, **and** vite `entries` key. Prefer:
|
|
|
278
290
|
camstack develop extend <package> --entry <new-id>
|
|
279
291
|
```
|
|
280
292
|
|
|
293
|
+
## Integration traps
|
|
294
|
+
|
|
295
|
+
An integration is a typed instance record (D1007, D996, D1009). These break it:
|
|
296
|
+
|
|
297
|
+
- **No addon-level settings for an integration.** No `globalSettingsSchema()`,
|
|
298
|
+
no `integration_settings` row, no `integrations.getSettings` /
|
|
299
|
+
`integrations.setSettings` (retired, being deleted). Everything the operator
|
|
300
|
+
configures is a field of the instance record; a secret is a `password` field
|
|
301
|
+
(`.meta({ secret: true })` on the kind).
|
|
302
|
+
- **Data changes go through a D987 migration with a read-back.** Move old rows
|
|
303
|
+
into records with a migration that writes, reads back and marks the field
|
|
304
|
+
it moved; never keep a dual read path that falls back to the old store.
|
|
305
|
+
- **The Gateway is a sibling, never a parent.** It is its own top-level device
|
|
306
|
+
carrying the `integrationId`; the equipment it reports is adopted as separate
|
|
307
|
+
top-level devices, never as its children.
|
|
308
|
+
- **A new exporter must provide `integration-instances`.** Every exporter is
|
|
309
|
+
multi-instance (`instanceMode: 'multiple'`): a target is an instance with a
|
|
310
|
+
MINTED id, what is exposed is keyed by that id, and a membership write always
|
|
311
|
+
names the target.
|
|
312
|
+
- **Per-device settings live only in `ctx.settings.*DeviceStore`;** per-device
|
|
313
|
+
DATA implements `device-removal-hook`, driven by a tombstone, never by a
|
|
314
|
+
device being absent from a list.
|
|
315
|
+
|
|
281
316
|
## Operator buttons (custom actions)
|
|
282
317
|
|
|
283
318
|
An addon-owned RPC on the `addons.custom` bridge, rendered by the settings form
|
|
@@ -32,8 +32,8 @@ closure, and an update of every node before anyone can call it. Check first:
|
|
|
32
32
|
|
|
33
33
|
- **Enumerating providers of an existing collection?**
|
|
34
34
|
`addons.listCapabilityProviders({ capName })` works even for `internal` caps.
|
|
35
|
-
- **An addon's own configuration?**
|
|
36
|
-
`
|
|
35
|
+
- **An addon's own configuration?** An integration INSTANCE record served through
|
|
36
|
+
`integration-instances` (D1007); an addon has no settings page of its own.
|
|
37
37
|
- **Enable / disable a provider?** `addons.setCapabilityProviderEnabled` (the
|
|
38
38
|
toggle is the ONE enable — D777).
|
|
39
39
|
- **A field on an existing method?** Additive output fields need only the
|