@installagent/sdk 0.4.1 → 0.6.0
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/dist/agent-mirror.js +22 -10
- package/dist/agent-templates.d.ts +10 -12
- package/dist/agent-templates.js +34 -6
- package/dist/doctor.d.ts +11 -1
- package/dist/doctor.js +24 -22
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/lefthook-hooks.d.ts +36 -0
- package/dist/lefthook-hooks.js +64 -0
- package/dist/n8n-defaults.d.ts +90 -0
- package/dist/n8n-defaults.js +153 -0
- package/dist/portal-admin.d.ts +128 -13
- package/dist/portal-admin.js +142 -28
- package/dist/pr-open.d.ts +45 -0
- package/dist/pr-open.js +98 -0
- package/dist/sync-repos.d.ts +8 -1
- package/dist/sync-repos.js +10 -9
- package/dist/triage-enable.js +20 -7
- package/package.json +1 -1
- package/templates/workspace-root/ONBOARDING.md +9 -7
- package/templates/workspace-root/skills/CLAUDE.md +4 -4
- package/templates/workspace-root/skills/README.md +2 -2
- package/templates/workspace-root/skills/ad-machine/SKILL.md +14 -18
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +14 -16
- package/templates/workspace-root/skills/client-latest/SKILL.md +14 -18
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +22 -16
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +11 -14
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +9 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +67 -19
- package/templates/workspace-root/skills/ia-cli/SKILL.md +14 -17
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +14 -20
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +2 -2
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +13 -15
- package/templates/workspace-root/skills/slack-voice/SKILL.md +50 -31
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +14 -15
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +13 -19
- package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +13 -15
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* House defaults for n8n workflows, and the lint that checks them.
|
|
3
|
+
*
|
|
4
|
+
* Measured 2026-10-15 on our shared instance: 0 of 48 workflows set a
|
|
5
|
+
* timeout, 33 of 48 had no retry anywhere, and 3 of 14 newer workflows had no
|
|
6
|
+
* error workflow — including a client-facing poller with 2,861 runs. A
|
|
7
|
+
* workflow without an error workflow fails in silence. These defaults live in
|
|
8
|
+
* every bank template; `ia agent create` fills the error workflow id and
|
|
9
|
+
* `ia agent lint` refuses a workflow without them.
|
|
10
|
+
*/
|
|
11
|
+
/** The shared instance's global error handler (`IA - global-error-handler`). */
|
|
12
|
+
export const IA_ERROR_WORKFLOW_ID = "vJt4USrJnUQG0EWo";
|
|
13
|
+
/** What a bank template carries instead of a real error workflow id. */
|
|
14
|
+
export const ERROR_WORKFLOW_PLACEHOLDER = "REPLACE_ME_ERROR_WORKFLOW_ID";
|
|
15
|
+
/**
|
|
16
|
+
* 30 minutes. A ceiling for a stuck run, not a budget for a normal one: the
|
|
17
|
+
* longest agent runs on the instance finish in a few minutes. n8n kills the
|
|
18
|
+
* execution at this point and the error workflow reports it.
|
|
19
|
+
*/
|
|
20
|
+
export const DEFAULT_EXECUTION_TIMEOUT_S = 1800;
|
|
21
|
+
/** The workflow-level `settings` every bank template carries. */
|
|
22
|
+
export const DEFAULT_WORKFLOW_SETTINGS = {
|
|
23
|
+
executionOrder: "v1",
|
|
24
|
+
errorWorkflow: ERROR_WORKFLOW_PLACEHOLDER,
|
|
25
|
+
executionTimeout: DEFAULT_EXECUTION_TIMEOUT_S,
|
|
26
|
+
saveDataErrorExecution: "all",
|
|
27
|
+
};
|
|
28
|
+
/** Node-level retry for read-only HTTP calls. Writes never retry: a retried POST can double-send. */
|
|
29
|
+
export const DEFAULT_GET_RETRY = {
|
|
30
|
+
retryOnFail: true,
|
|
31
|
+
maxTries: 3,
|
|
32
|
+
waitBetweenTries: 5000,
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* `<client-slug or IA> - <slug> - <purpose>` (team-web hub, Infra → n8n).
|
|
36
|
+
* Slugs are lowercase kebab-case; the purpose is free text.
|
|
37
|
+
*/
|
|
38
|
+
export const WORKFLOW_NAME_PATTERN = /^(IA|[a-z0-9]+(?:-[a-z0-9]+)*) - [a-z0-9]+(?:-[a-z0-9]+)* - \S.*$/;
|
|
39
|
+
/** An HTTP Request node whose method is GET (n8n's default when unset). */
|
|
40
|
+
export function isGetHttpNode(node) {
|
|
41
|
+
if (node.type !== "n8n-nodes-base.httpRequest")
|
|
42
|
+
return false;
|
|
43
|
+
const method = node.parameters?.method;
|
|
44
|
+
return method === undefined || method === "GET";
|
|
45
|
+
}
|
|
46
|
+
/** True for an error handler itself: it must not point at an error workflow. */
|
|
47
|
+
function isErrorHandler(wf) {
|
|
48
|
+
return (wf.nodes ?? []).some((n) => n.type === "n8n-nodes-base.errorTrigger");
|
|
49
|
+
}
|
|
50
|
+
export function lintN8nWorkflow(wf, options = {}) {
|
|
51
|
+
const findings = [];
|
|
52
|
+
const settings = wf.settings ?? {};
|
|
53
|
+
const name = typeof wf.name === "string" ? wf.name : "";
|
|
54
|
+
if (!options.template && !WORKFLOW_NAME_PATTERN.test(name)) {
|
|
55
|
+
findings.push({
|
|
56
|
+
level: "error",
|
|
57
|
+
rule: "name-pattern",
|
|
58
|
+
message: `name "${name}" is not \`<client-slug or IA> - <slug> - <purpose>\` (use \`ia agent create --client <slug>\`)`,
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
if (!isErrorHandler(wf)) {
|
|
62
|
+
const errorWorkflow = settings.errorWorkflow;
|
|
63
|
+
if (options.template) {
|
|
64
|
+
if (errorWorkflow !== ERROR_WORKFLOW_PLACEHOLDER) {
|
|
65
|
+
findings.push({
|
|
66
|
+
level: "error",
|
|
67
|
+
rule: "error-workflow",
|
|
68
|
+
message: `settings.errorWorkflow must be "${ERROR_WORKFLOW_PLACEHOLDER}" in a bank template (found ${JSON.stringify(errorWorkflow ?? null)})`,
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
else if (typeof errorWorkflow !== "string" ||
|
|
73
|
+
errorWorkflow === "" ||
|
|
74
|
+
errorWorkflow.startsWith("REPLACE_ME")) {
|
|
75
|
+
findings.push({
|
|
76
|
+
level: "error",
|
|
77
|
+
rule: "error-workflow",
|
|
78
|
+
message: `settings.errorWorkflow is not set, so a failure reports nowhere (shared instance: ${IA_ERROR_WORKFLOW_ID})`,
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
const timeout = settings.executionTimeout;
|
|
83
|
+
if (typeof timeout !== "number" || timeout <= 0) {
|
|
84
|
+
findings.push({
|
|
85
|
+
level: "error",
|
|
86
|
+
rule: "timeout",
|
|
87
|
+
message: `settings.executionTimeout is not set, so a stuck run never ends (house default ${DEFAULT_EXECUTION_TIMEOUT_S} s)`,
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
for (const node of wf.nodes ?? []) {
|
|
91
|
+
if (isGetHttpNode(node) && node.retryOnFail !== true) {
|
|
92
|
+
findings.push({
|
|
93
|
+
level: "warn",
|
|
94
|
+
rule: "get-retry",
|
|
95
|
+
message: `node "${String(node.name)}" is a GET with no retry (Settings → Retry On Fail, 3 tries, 5000 ms)`,
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
return findings;
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Turn a bank template into a client workflow: house settings filled in, the
|
|
103
|
+
* placeholder replaced by a real error workflow id, and (with a client slug)
|
|
104
|
+
* the house name. Keys the template already sets win over the defaults.
|
|
105
|
+
*/
|
|
106
|
+
export function applyClientDefaults(wf, opts) {
|
|
107
|
+
const settings = {
|
|
108
|
+
...DEFAULT_WORKFLOW_SETTINGS,
|
|
109
|
+
...(wf.settings ?? {}),
|
|
110
|
+
};
|
|
111
|
+
const isHandler = (wf.nodes ?? []).some((n) => n.type === "n8n-nodes-base.errorTrigger");
|
|
112
|
+
if (isHandler)
|
|
113
|
+
delete settings.errorWorkflow;
|
|
114
|
+
else if (typeof settings.errorWorkflow !== "string" ||
|
|
115
|
+
settings.errorWorkflow === "" ||
|
|
116
|
+
settings.errorWorkflow.startsWith("REPLACE_ME")) {
|
|
117
|
+
settings.errorWorkflow = opts.errorWorkflowId ?? IA_ERROR_WORKFLOW_ID;
|
|
118
|
+
}
|
|
119
|
+
const out = { ...wf, settings };
|
|
120
|
+
if (opts.client)
|
|
121
|
+
out.name = clientWorkflowName(opts.client, opts.template, String(wf.name ?? ""));
|
|
122
|
+
return out;
|
|
123
|
+
}
|
|
124
|
+
/** `<client> - <template slug> - <purpose>`; the purpose is the template title without bank markers. */
|
|
125
|
+
export function clientWorkflowName(client, template, templateTitle) {
|
|
126
|
+
const purpose = templateTitle
|
|
127
|
+
.replace(/\s*\(template\)\s*$/i, "")
|
|
128
|
+
.replace(/^(Team|IA)\s+-\s+/, "")
|
|
129
|
+
.trim() || template;
|
|
130
|
+
return `${client} - ${template} - ${purpose}`;
|
|
131
|
+
}
|
|
132
|
+
/** `ia agent lint`: read each workflow JSON and lint it. A file that is not JSON fails. */
|
|
133
|
+
export async function lintWorkflowFiles(files, options = {}) {
|
|
134
|
+
const { readFile } = await import("node:fs/promises");
|
|
135
|
+
const results = [];
|
|
136
|
+
for (const file of files) {
|
|
137
|
+
let findings;
|
|
138
|
+
try {
|
|
139
|
+
findings = lintN8nWorkflow(JSON.parse(await readFile(file, "utf8")), options);
|
|
140
|
+
}
|
|
141
|
+
catch (error) {
|
|
142
|
+
findings = [
|
|
143
|
+
{
|
|
144
|
+
level: "error",
|
|
145
|
+
rule: "unreadable",
|
|
146
|
+
message: `cannot read as workflow JSON: ${error instanceof Error ? error.message : String(error)}`,
|
|
147
|
+
},
|
|
148
|
+
];
|
|
149
|
+
}
|
|
150
|
+
results.push({ file, findings, failed: findings.some((f) => f.level === "error") });
|
|
151
|
+
}
|
|
152
|
+
return { ok: results.every((r) => !r.failed), results };
|
|
153
|
+
}
|
package/dist/portal-admin.d.ts
CHANGED
|
@@ -38,18 +38,43 @@ export interface PortalOrg {
|
|
|
38
38
|
slackChannelId?: string | null;
|
|
39
39
|
users: PortalOrgUser[];
|
|
40
40
|
}
|
|
41
|
-
|
|
41
|
+
/**
|
|
42
|
+
* What kind of thing a portal build is (2026-10-13). `agent` = an automation
|
|
43
|
+
* that runs as an n8n workflow (workflow id required). `app` = something we
|
|
44
|
+
* built that has no runs — a web app or website — with an optional https
|
|
45
|
+
* `url` and NO workflow id.
|
|
46
|
+
*/
|
|
47
|
+
export type PortalBuildType = "agent" | "app";
|
|
48
|
+
export declare const PORTAL_BUILD_TYPES: readonly PortalBuildType[];
|
|
49
|
+
/**
|
|
50
|
+
* One row of the portal's builds registry (named `agents` before 2026-10-13).
|
|
51
|
+
* The wire field is `workflowId` (the portal's `n8n_workflow_id` column).
|
|
52
|
+
*/
|
|
53
|
+
export interface PortalBuild {
|
|
42
54
|
org: string;
|
|
43
55
|
slug: string;
|
|
44
56
|
name: string;
|
|
45
57
|
description: string;
|
|
46
|
-
|
|
58
|
+
/** The n8n workflow id the build reports as; null for an app build. */
|
|
59
|
+
workflowId: string | null;
|
|
47
60
|
status: "active" | "paused" | "retired";
|
|
48
61
|
n8nActive: boolean | null;
|
|
49
62
|
lastSyncedAt: string | null;
|
|
50
63
|
/** Set = an email-triage agent of that provider. Absent on portals older than 2026-09-29. */
|
|
51
64
|
triageProvider?: PortalTriageProvider | null;
|
|
65
|
+
/** Absent on portals older than 2026-10-13 — read it through `portalBuildType()`. */
|
|
66
|
+
buildType?: PortalBuildType;
|
|
67
|
+
/** An app build's https address; null/absent when there is none. */
|
|
68
|
+
url?: string | null;
|
|
69
|
+
/** ISO time the build was registered (its go-live date). Absent on portals older than 2026-10-16. */
|
|
70
|
+
createdAt?: string;
|
|
52
71
|
}
|
|
72
|
+
/** Old name of `PortalBuild`, kept as an alias until the full rename. */
|
|
73
|
+
export type PortalAgent = PortalBuild;
|
|
74
|
+
/** The build's type; a portal older than 2026-10-13 sends none, and then every build is an agent. */
|
|
75
|
+
export declare function portalBuildType(build: PortalBuild): PortalBuildType;
|
|
76
|
+
/** The build's workflow id when it is an agent with one; null for an app (nothing to run). */
|
|
77
|
+
export declare function portalBuildWorkflowId(build: PortalBuild): string | null;
|
|
53
78
|
export interface PortalCreateOrgInput {
|
|
54
79
|
slug: string;
|
|
55
80
|
name: string;
|
|
@@ -83,15 +108,47 @@ export interface PortalAddUserResult {
|
|
|
83
108
|
slug: string;
|
|
84
109
|
user: PortalOrgUser;
|
|
85
110
|
}
|
|
111
|
+
/**
|
|
112
|
+
* Change one contact. Name it by `email` (case-insensitive) OR by `name` (only
|
|
113
|
+
* a contact with no email) — exactly one. Change `role`, `status` or both.
|
|
114
|
+
*/
|
|
115
|
+
export interface PortalSetUserInput {
|
|
116
|
+
slug: string;
|
|
117
|
+
email?: string;
|
|
118
|
+
name?: string;
|
|
119
|
+
role?: "member" | "owner";
|
|
120
|
+
status?: "active" | "disabled";
|
|
121
|
+
}
|
|
122
|
+
export interface PortalSetUserResult {
|
|
123
|
+
slug: string;
|
|
124
|
+
user: PortalOrgUser;
|
|
125
|
+
/** False when the contact already had these values (nothing was written). */
|
|
126
|
+
changed: boolean;
|
|
127
|
+
}
|
|
86
128
|
export interface PortalListOrgsResult {
|
|
87
129
|
orgs: PortalOrg[];
|
|
88
130
|
}
|
|
89
|
-
export interface
|
|
131
|
+
export interface PortalCreateBuildInput {
|
|
90
132
|
slug: string;
|
|
91
|
-
|
|
133
|
+
/** The build slug, e.g. "follow-up". */
|
|
134
|
+
build: string;
|
|
92
135
|
name: string;
|
|
93
136
|
description: string;
|
|
94
|
-
|
|
137
|
+
/** Default "agent". */
|
|
138
|
+
buildType?: PortalBuildType;
|
|
139
|
+
/** Required for an agent; refused for an app. */
|
|
140
|
+
workflowId?: string;
|
|
141
|
+
/** Optional https address (an app's web app or website). */
|
|
142
|
+
url?: string;
|
|
143
|
+
}
|
|
144
|
+
/** Old input shape of `portalCreateAgent`: the build slug is `agent`. */
|
|
145
|
+
export type PortalCreateAgentInput = Omit<PortalCreateBuildInput, "build"> & {
|
|
146
|
+
agent: string;
|
|
147
|
+
};
|
|
148
|
+
export interface PortalSetBuildStatusInput {
|
|
149
|
+
slug: string;
|
|
150
|
+
build: string;
|
|
151
|
+
status: "active" | "paused" | "retired";
|
|
95
152
|
}
|
|
96
153
|
export interface PortalSetAgentStatusInput {
|
|
97
154
|
slug: string;
|
|
@@ -131,9 +188,14 @@ export interface PortalSetAgentWorkflowResult {
|
|
|
131
188
|
/** False when the agent already pointed there — the call is idempotent. */
|
|
132
189
|
changed: boolean;
|
|
133
190
|
}
|
|
191
|
+
/**
|
|
192
|
+
* The portal's list answer. The key stays `agents` on the wire (the
|
|
193
|
+
* `/api/admin/agents` route); every item is a build of either type.
|
|
194
|
+
*/
|
|
134
195
|
export interface PortalListAgentsResult {
|
|
135
|
-
agents:
|
|
196
|
+
agents: PortalBuild[];
|
|
136
197
|
}
|
|
198
|
+
export type PortalListBuildsResult = PortalListAgentsResult;
|
|
137
199
|
export interface PortalAgentSyncRow {
|
|
138
200
|
org: string;
|
|
139
201
|
agent: string;
|
|
@@ -159,23 +221,69 @@ export declare function portalSetDriveFolder(input: {
|
|
|
159
221
|
folderId: string;
|
|
160
222
|
}, options?: PortalAdminOptions): Promise<PortalSetDriveFolderResult>;
|
|
161
223
|
export declare function portalAddUser(input: PortalAddUserInput, options?: PortalAdminOptions): Promise<PortalAddUserResult>;
|
|
224
|
+
/**
|
|
225
|
+
* Change a contact's role and/or status (PATCH /api/admin/users). The portal
|
|
226
|
+
* never deletes a contact: `disabled` keeps the row (uploads, feedback and
|
|
227
|
+
* sign-in links point at it) and stops new magic-link sign-ins. Errors name
|
|
228
|
+
* the field, never the email or name.
|
|
229
|
+
*/
|
|
230
|
+
export declare function portalSetUser(input: PortalSetUserInput, options?: PortalAdminOptions): Promise<PortalSetUserResult>;
|
|
162
231
|
export declare function portalListOrgs(options?: PortalAdminOptions): Promise<PortalListOrgsResult>;
|
|
232
|
+
/**
|
|
233
|
+
* The client-side check of a create: an agent needs its n8n workflow id, an
|
|
234
|
+
* app must not carry one, and a url (either type) must be https. The portal
|
|
235
|
+
* re-validates; this only stops an obvious mistake before the request.
|
|
236
|
+
*/
|
|
237
|
+
export declare function validatePortalBuildFields(input: {
|
|
238
|
+
buildType?: string;
|
|
239
|
+
workflowId?: string;
|
|
240
|
+
url?: string;
|
|
241
|
+
}): {
|
|
242
|
+
buildType: PortalBuildType;
|
|
243
|
+
workflowId: string | null;
|
|
244
|
+
url: string | null;
|
|
245
|
+
};
|
|
246
|
+
/** Register a build (an agent or an app) for an org. */
|
|
247
|
+
export declare function portalCreateBuild(input: PortalCreateBuildInput, options?: PortalAdminOptions): Promise<{
|
|
248
|
+
agent: PortalBuild;
|
|
249
|
+
}>;
|
|
250
|
+
/** Old name of `portalCreateBuild` (the build slug is `agent`). */
|
|
163
251
|
export declare function portalCreateAgent(input: PortalCreateAgentInput, options?: PortalAdminOptions): Promise<{
|
|
164
|
-
agent:
|
|
252
|
+
agent: PortalBuild;
|
|
165
253
|
}>;
|
|
254
|
+
export declare function portalSetBuildStatus(input: PortalSetBuildStatusInput, options?: PortalAdminOptions): Promise<PortalSetAgentStatusResult>;
|
|
255
|
+
/** Old name of `portalSetBuildStatus`. */
|
|
166
256
|
export declare function portalSetAgentStatus(input: PortalSetAgentStatusInput, options?: PortalAdminOptions): Promise<PortalSetAgentStatusResult>;
|
|
167
257
|
/**
|
|
168
|
-
* Rename
|
|
258
|
+
* Rename a build — the client-facing label on its card. The build slug is the
|
|
169
259
|
* stable identifier, so a rename breaks no reference.
|
|
170
260
|
*/
|
|
261
|
+
export declare function portalSetBuildName(input: {
|
|
262
|
+
slug: string;
|
|
263
|
+
build: string;
|
|
264
|
+
name: string;
|
|
265
|
+
}, options?: PortalAdminOptions): Promise<PortalSetAgentNameResult>;
|
|
266
|
+
/** Old name of `portalSetBuildName`. */
|
|
171
267
|
export declare function portalSetAgentName(input: PortalSetAgentNameInput, options?: PortalAdminOptions): Promise<PortalSetAgentNameResult>;
|
|
172
268
|
/**
|
|
173
|
-
* Repoint an agent at a different n8n workflow — for a version bump (v2
|
|
269
|
+
* Repoint an agent build at a different n8n workflow — for a version bump (v2
|
|
174
270
|
* replacing a retired v1), which is the same agent from the client's side.
|
|
175
271
|
* The row keeps its slug, name, and run history; the portal re-observes the
|
|
176
|
-
* new workflow's live state on the next sync.
|
|
272
|
+
* new workflow's live state on the next sync. An app build has no workflow;
|
|
273
|
+
* the portal refuses this call for one.
|
|
177
274
|
*/
|
|
275
|
+
export declare function portalSetBuildWorkflow(input: {
|
|
276
|
+
slug: string;
|
|
277
|
+
build: string;
|
|
278
|
+
workflowId: string;
|
|
279
|
+
}, options?: PortalAdminOptions): Promise<PortalSetAgentWorkflowResult>;
|
|
280
|
+
/** Old name of `portalSetBuildWorkflow`. */
|
|
178
281
|
export declare function portalSetAgentWorkflow(input: PortalSetAgentWorkflowInput, options?: PortalAdminOptions): Promise<PortalSetAgentWorkflowResult>;
|
|
282
|
+
/** Every registered build (agents and apps), for all orgs or one. */
|
|
283
|
+
export declare function portalListBuilds(input?: {
|
|
284
|
+
slug?: string;
|
|
285
|
+
}, options?: PortalAdminOptions): Promise<PortalListBuildsResult>;
|
|
286
|
+
/** Old name of `portalListBuilds`. */
|
|
179
287
|
export declare function portalListAgents(input?: {
|
|
180
288
|
slug?: string;
|
|
181
289
|
}, options?: PortalAdminOptions): Promise<PortalListAgentsResult>;
|
|
@@ -188,10 +296,17 @@ export interface PortalSetAgentTriageResult {
|
|
|
188
296
|
triageProvider: PortalTriageProvider | null;
|
|
189
297
|
}
|
|
190
298
|
/**
|
|
191
|
-
* Mark an agent as an email-triage agent of one provider, or clear it
|
|
192
|
-
* null. Only a triage agent may write classification rows, and the
|
|
193
|
-
* decides the row shape the portal accepts.
|
|
299
|
+
* Mark an agent build as an email-triage agent of one provider, or clear it
|
|
300
|
+
* with null. Only a triage agent may write classification rows, and the
|
|
301
|
+
* provider decides the row shape the portal accepts. An app build never runs,
|
|
302
|
+
* so it is never a triage agent.
|
|
194
303
|
*/
|
|
304
|
+
export declare function portalSetBuildTriage(input: {
|
|
305
|
+
slug: string;
|
|
306
|
+
build: string;
|
|
307
|
+
provider: PortalTriageProvider | null;
|
|
308
|
+
}, options?: PortalAdminOptions): Promise<PortalSetAgentTriageResult>;
|
|
309
|
+
/** Old name of `portalSetBuildTriage`. */
|
|
195
310
|
export declare function portalSetAgentTriage(input: {
|
|
196
311
|
slug: string;
|
|
197
312
|
agent: string;
|
package/dist/portal-admin.js
CHANGED
|
@@ -28,6 +28,18 @@ export class PortalRequestError extends Error {
|
|
|
28
28
|
this.serverError = serverError;
|
|
29
29
|
}
|
|
30
30
|
}
|
|
31
|
+
export const PORTAL_BUILD_TYPES = ["agent", "app"];
|
|
32
|
+
/** The build's type; a portal older than 2026-10-13 sends none, and then every build is an agent. */
|
|
33
|
+
export function portalBuildType(build) {
|
|
34
|
+
return build.buildType ?? "agent";
|
|
35
|
+
}
|
|
36
|
+
/** The build's workflow id when it is an agent with one; null for an app (nothing to run). */
|
|
37
|
+
export function portalBuildWorkflowId(build) {
|
|
38
|
+
if (portalBuildType(build) !== "agent")
|
|
39
|
+
return null;
|
|
40
|
+
const id = build.workflowId?.trim();
|
|
41
|
+
return id ? id : null;
|
|
42
|
+
}
|
|
31
43
|
/** Lowercase then validate, matching the server (and the old script). */
|
|
32
44
|
function normalizeSlug(value, field) {
|
|
33
45
|
const slug = value.toLowerCase();
|
|
@@ -102,65 +114,162 @@ export async function portalAddUser(input, options = {}) {
|
|
|
102
114
|
...(input.role ? { role: input.role } : {}),
|
|
103
115
|
});
|
|
104
116
|
}
|
|
117
|
+
/**
|
|
118
|
+
* Change a contact's role and/or status (PATCH /api/admin/users). The portal
|
|
119
|
+
* never deletes a contact: `disabled` keeps the row (uploads, feedback and
|
|
120
|
+
* sign-in links point at it) and stops new magic-link sign-ins. Errors name
|
|
121
|
+
* the field, never the email or name.
|
|
122
|
+
*/
|
|
123
|
+
export async function portalSetUser(input, options = {}) {
|
|
124
|
+
const slug = normalizeSlug(input.slug, "org");
|
|
125
|
+
const email = input.email?.trim();
|
|
126
|
+
const name = input.name?.trim();
|
|
127
|
+
if (Boolean(email) === Boolean(name)) {
|
|
128
|
+
throw new Error("give exactly one of --email or --name to find the contact");
|
|
129
|
+
}
|
|
130
|
+
if (input.role !== undefined && input.role !== "member" && input.role !== "owner") {
|
|
131
|
+
throw new Error("role must be member|owner");
|
|
132
|
+
}
|
|
133
|
+
if (input.status !== undefined && input.status !== "active" && input.status !== "disabled") {
|
|
134
|
+
throw new Error("status must be active|disabled");
|
|
135
|
+
}
|
|
136
|
+
if (input.role === undefined && input.status === undefined) {
|
|
137
|
+
throw new Error("give --role and/or --status to change");
|
|
138
|
+
}
|
|
139
|
+
return portalRequest("PATCH", "/api/admin/users", options, {
|
|
140
|
+
slug,
|
|
141
|
+
...(email ? { email } : { name }),
|
|
142
|
+
...(input.role ? { role: input.role } : {}),
|
|
143
|
+
...(input.status ? { status: input.status } : {}),
|
|
144
|
+
});
|
|
145
|
+
}
|
|
105
146
|
export async function portalListOrgs(options = {}) {
|
|
106
147
|
return portalRequest("GET", "/api/admin/orgs", options);
|
|
107
148
|
}
|
|
108
|
-
|
|
149
|
+
// ─── Builds registry (named `agents` before 2026-10-13) ─────────────────────
|
|
150
|
+
//
|
|
151
|
+
// The portal renamed its `agents` registry to `builds` and added a build type
|
|
152
|
+
// (agent | app). The SDK still calls the `/api/admin/agents*` routes: they
|
|
153
|
+
// stay as aliases on the portal, so these calls work both before and after
|
|
154
|
+
// the portal deploy. When the full rename happens, switch every path below
|
|
155
|
+
// to `/api/admin/builds*` (same bodies) and drop the `*Agent*` aliases — see
|
|
156
|
+
// docs/spec.md § "Portal builds rename (2026-10-13)". The request body keeps
|
|
157
|
+
// the `agent` key: it is the portal's wire name for the build slug.
|
|
158
|
+
const BUILDS_PATH = "/api/admin/agents";
|
|
159
|
+
function isHttpsUrl(value) {
|
|
160
|
+
try {
|
|
161
|
+
return new URL(value).protocol === "https:";
|
|
162
|
+
}
|
|
163
|
+
catch {
|
|
164
|
+
return false;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* The client-side check of a create: an agent needs its n8n workflow id, an
|
|
169
|
+
* app must not carry one, and a url (either type) must be https. The portal
|
|
170
|
+
* re-validates; this only stops an obvious mistake before the request.
|
|
171
|
+
*/
|
|
172
|
+
export function validatePortalBuildFields(input) {
|
|
173
|
+
const buildType = input.buildType ?? "agent";
|
|
174
|
+
if (!PORTAL_BUILD_TYPES.includes(buildType)) {
|
|
175
|
+
throw new Error(`build type must be ${PORTAL_BUILD_TYPES.join("|")} (got "${buildType}")`);
|
|
176
|
+
}
|
|
177
|
+
const workflowId = input.workflowId?.trim() || null;
|
|
178
|
+
const url = input.url?.trim() || null;
|
|
179
|
+
if (buildType === "agent" && !workflowId) {
|
|
180
|
+
throw new Error("an agent build needs its n8n workflow id (--workflow)");
|
|
181
|
+
}
|
|
182
|
+
if (buildType === "app" && workflowId) {
|
|
183
|
+
throw new Error("an app build has no n8n workflow — drop --workflow, or use --type agent");
|
|
184
|
+
}
|
|
185
|
+
if (url && !isHttpsUrl(url)) {
|
|
186
|
+
throw new Error(`url must be an https:// address (got "${url}")`);
|
|
187
|
+
}
|
|
188
|
+
return { buildType: buildType, workflowId, url };
|
|
189
|
+
}
|
|
190
|
+
/** Register a build (an agent or an app) for an org. */
|
|
191
|
+
export async function portalCreateBuild(input, options = {}) {
|
|
109
192
|
const slug = normalizeSlug(input.slug, "org");
|
|
110
|
-
const
|
|
111
|
-
|
|
193
|
+
const build = normalizeSlug(input.build, "build");
|
|
194
|
+
const fields = validatePortalBuildFields(input);
|
|
195
|
+
return portalRequest("POST", BUILDS_PATH, options, {
|
|
112
196
|
slug,
|
|
113
|
-
agent,
|
|
197
|
+
agent: build,
|
|
114
198
|
name: input.name,
|
|
115
199
|
description: input.description,
|
|
116
|
-
|
|
200
|
+
buildType: fields.buildType,
|
|
201
|
+
...(fields.workflowId ? { workflowId: fields.workflowId } : {}),
|
|
202
|
+
...(fields.url ? { url: fields.url } : {}),
|
|
117
203
|
});
|
|
118
204
|
}
|
|
119
|
-
|
|
205
|
+
/** Old name of `portalCreateBuild` (the build slug is `agent`). */
|
|
206
|
+
export async function portalCreateAgent(input, options = {}) {
|
|
207
|
+
const { agent, ...rest } = input;
|
|
208
|
+
return portalCreateBuild({ ...rest, build: agent }, options);
|
|
209
|
+
}
|
|
210
|
+
export async function portalSetBuildStatus(input, options = {}) {
|
|
120
211
|
const slug = normalizeSlug(input.slug, "org");
|
|
121
|
-
const
|
|
212
|
+
const build = normalizeSlug(input.build, "build");
|
|
122
213
|
if (input.status !== "active" && input.status !== "paused" && input.status !== "retired") {
|
|
123
214
|
throw new Error("status must be active|paused|retired");
|
|
124
215
|
}
|
|
125
|
-
return portalRequest("POST",
|
|
216
|
+
return portalRequest("POST", `${BUILDS_PATH}/status`, options, {
|
|
126
217
|
slug,
|
|
127
|
-
agent,
|
|
218
|
+
agent: build,
|
|
128
219
|
status: input.status,
|
|
129
220
|
});
|
|
130
221
|
}
|
|
222
|
+
/** Old name of `portalSetBuildStatus`. */
|
|
223
|
+
export async function portalSetAgentStatus(input, options = {}) {
|
|
224
|
+
return portalSetBuildStatus({ slug: input.slug, build: input.agent, status: input.status }, options);
|
|
225
|
+
}
|
|
131
226
|
/**
|
|
132
|
-
* Rename
|
|
227
|
+
* Rename a build — the client-facing label on its card. The build slug is the
|
|
133
228
|
* stable identifier, so a rename breaks no reference.
|
|
134
229
|
*/
|
|
135
|
-
export async function
|
|
230
|
+
export async function portalSetBuildName(input, options = {}) {
|
|
136
231
|
const slug = normalizeSlug(input.slug, "org");
|
|
137
|
-
const
|
|
232
|
+
const build = normalizeSlug(input.build, "build");
|
|
138
233
|
const name = input.name.trim();
|
|
139
234
|
if (!name)
|
|
140
235
|
throw new Error("name required");
|
|
141
|
-
return portalRequest("POST",
|
|
236
|
+
return portalRequest("POST", `${BUILDS_PATH}/name`, options, { slug, agent: build, name });
|
|
237
|
+
}
|
|
238
|
+
/** Old name of `portalSetBuildName`. */
|
|
239
|
+
export async function portalSetAgentName(input, options = {}) {
|
|
240
|
+
return portalSetBuildName({ slug: input.slug, build: input.agent, name: input.name }, options);
|
|
142
241
|
}
|
|
143
242
|
/**
|
|
144
|
-
* Repoint an agent at a different n8n workflow — for a version bump (v2
|
|
243
|
+
* Repoint an agent build at a different n8n workflow — for a version bump (v2
|
|
145
244
|
* replacing a retired v1), which is the same agent from the client's side.
|
|
146
245
|
* The row keeps its slug, name, and run history; the portal re-observes the
|
|
147
|
-
* new workflow's live state on the next sync.
|
|
246
|
+
* new workflow's live state on the next sync. An app build has no workflow;
|
|
247
|
+
* the portal refuses this call for one.
|
|
148
248
|
*/
|
|
149
|
-
export async function
|
|
249
|
+
export async function portalSetBuildWorkflow(input, options = {}) {
|
|
150
250
|
const slug = normalizeSlug(input.slug, "org");
|
|
151
|
-
const
|
|
251
|
+
const build = normalizeSlug(input.build, "build");
|
|
152
252
|
const workflowId = input.workflowId.trim();
|
|
153
253
|
if (!workflowId)
|
|
154
254
|
throw new Error("workflowId required");
|
|
155
|
-
return portalRequest("POST",
|
|
255
|
+
return portalRequest("POST", `${BUILDS_PATH}/workflow-id`, options, {
|
|
156
256
|
slug,
|
|
157
|
-
agent,
|
|
257
|
+
agent: build,
|
|
158
258
|
workflowId,
|
|
159
259
|
});
|
|
160
260
|
}
|
|
161
|
-
|
|
261
|
+
/** Old name of `portalSetBuildWorkflow`. */
|
|
262
|
+
export async function portalSetAgentWorkflow(input, options = {}) {
|
|
263
|
+
return portalSetBuildWorkflow({ slug: input.slug, build: input.agent, workflowId: input.workflowId }, options);
|
|
264
|
+
}
|
|
265
|
+
/** Every registered build (agents and apps), for all orgs or one. */
|
|
266
|
+
export async function portalListBuilds(input = {}, options = {}) {
|
|
162
267
|
const query = input.slug ? `?slug=${encodeURIComponent(normalizeSlug(input.slug, "org"))}` : "";
|
|
163
|
-
return portalRequest("GET",
|
|
268
|
+
return portalRequest("GET", `${BUILDS_PATH}${query}`, options);
|
|
269
|
+
}
|
|
270
|
+
/** Old name of `portalListBuilds`. */
|
|
271
|
+
export async function portalListAgents(input = {}, options = {}) {
|
|
272
|
+
return portalListBuilds(input, options);
|
|
164
273
|
}
|
|
165
274
|
export async function portalSyncRuns(input = {}, options = {}) {
|
|
166
275
|
if (input.days !== undefined) {
|
|
@@ -189,20 +298,25 @@ function assertProvider(provider) {
|
|
|
189
298
|
}
|
|
190
299
|
}
|
|
191
300
|
/**
|
|
192
|
-
* Mark an agent as an email-triage agent of one provider, or clear it
|
|
193
|
-
* null. Only a triage agent may write classification rows, and the
|
|
194
|
-
* decides the row shape the portal accepts.
|
|
301
|
+
* Mark an agent build as an email-triage agent of one provider, or clear it
|
|
302
|
+
* with null. Only a triage agent may write classification rows, and the
|
|
303
|
+
* provider decides the row shape the portal accepts. An app build never runs,
|
|
304
|
+
* so it is never a triage agent.
|
|
195
305
|
*/
|
|
196
|
-
export async function
|
|
306
|
+
export async function portalSetBuildTriage(input, options = {}) {
|
|
197
307
|
const slug = normalizeSlug(input.slug, "org");
|
|
198
|
-
const
|
|
308
|
+
const build = normalizeSlug(input.build, "build");
|
|
199
309
|
assertProvider(input.provider);
|
|
200
|
-
return portalRequest("POST",
|
|
310
|
+
return portalRequest("POST", `${BUILDS_PATH}/triage`, options, {
|
|
201
311
|
slug,
|
|
202
|
-
agent,
|
|
312
|
+
agent: build,
|
|
203
313
|
provider: input.provider,
|
|
204
314
|
});
|
|
205
315
|
}
|
|
316
|
+
/** Old name of `portalSetBuildTriage`. */
|
|
317
|
+
export async function portalSetAgentTriage(input, options = {}) {
|
|
318
|
+
return portalSetBuildTriage({ slug: input.slug, build: input.agent, provider: input.provider }, options);
|
|
319
|
+
}
|
|
206
320
|
/** Where the weekly triage digest posts for this client; null = no digest. */
|
|
207
321
|
export async function portalSetOrgSlackChannel(input, options = {}) {
|
|
208
322
|
const slug = normalizeSlug(input.slug, "org");
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { type ExecFileFn } from "./exec.js";
|
|
2
|
+
/**
|
|
3
|
+
* `ia pr open` — push the current branch and open a DRAFT pull request, with
|
|
4
|
+
* the three checks that the Slack Merge button made necessary:
|
|
5
|
+
*
|
|
6
|
+
* 1. The gh account is the workspace's work account (`.github-account` at the
|
|
7
|
+
* workspace root). A PR under a personal account lands on the wrong identity
|
|
8
|
+
* and lacks org access.
|
|
9
|
+
* 2. The branch has no MERGED pull request. The Merge button squash-merges and
|
|
10
|
+
* deletes the branch about a minute after a PR opens; a later push to the
|
|
11
|
+
* same branch was silently lost (6 incidents in 20 days, Oct 2026).
|
|
12
|
+
* 3. The branch has no OPEN pull request. More commits on an open PR is the
|
|
13
|
+
* same trap one click later: open a new PR per slice.
|
|
14
|
+
*
|
|
15
|
+
* The PR opens as a draft, so no Slack card (and no Merge button) exists until
|
|
16
|
+
* someone marks it ready on purpose.
|
|
17
|
+
*/
|
|
18
|
+
export interface PrOpenOptions {
|
|
19
|
+
/** The git checkout to open the PR from. Defaults to the current dir. */
|
|
20
|
+
repoDir?: string;
|
|
21
|
+
/** installagent/ workspace root, for `.github-account`. Found from repoDir when unset. */
|
|
22
|
+
workspaceDir?: string;
|
|
23
|
+
title?: string;
|
|
24
|
+
body?: string;
|
|
25
|
+
base?: string;
|
|
26
|
+
/** Open it ready for review (posts the Slack card at once). Default false. */
|
|
27
|
+
ready?: boolean;
|
|
28
|
+
/** Run the checks only; push nothing and open nothing. */
|
|
29
|
+
dryRun?: boolean;
|
|
30
|
+
execFileImpl?: ExecFileFn;
|
|
31
|
+
}
|
|
32
|
+
export interface PrOpenResult {
|
|
33
|
+
repo: string;
|
|
34
|
+
branch: string;
|
|
35
|
+
base: string;
|
|
36
|
+
account: string;
|
|
37
|
+
draft: boolean;
|
|
38
|
+
/** Undefined on a dry run. */
|
|
39
|
+
url?: string;
|
|
40
|
+
dryRun: boolean;
|
|
41
|
+
}
|
|
42
|
+
/** `owner/repo` from a GitHub remote URL (ssh or https). */
|
|
43
|
+
export declare function parseGithubRemote(url: string): string | undefined;
|
|
44
|
+
export declare function expectedGithubAccount(workspaceDir: string | null): string | undefined;
|
|
45
|
+
export declare function prOpen(options?: PrOpenOptions): Promise<PrOpenResult>;
|