@arbium/enterprise-agent-connect 0.1.2-dev.d2aa5ca → 0.2.1-dev.fd7a648

package/dist/packages/connector-kit/src/connector.d.ts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import type { MicrosoftClient } from "../../../connectors/microsoft/client.js";
 import type { Toolset } from "./common.js";
 import type { Vendor } from "./types.js";
 declare const settingSchema: z.ZodObject<{
@@ -27,8 +26,8 @@ export declare const setupStep: z.ZodObject<{
     click: z.ZodOptional<z.ZodArray<z.ZodString>>;
     clickUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
     siteRole: z.ZodOptional<z.ZodEnum<{
-        write: "write";
         read: "read";
+        write: "write";
     }>>;
     agentCheck: z.ZodOptional<z.ZodBoolean>;
     confirm: z.ZodOptional<z.ZodString>;
@@ -53,6 +52,7 @@ declare const probeSchema: z.ZodUnion<readonly [z.ZodObject<{
     path: z.ZodString;
     label: z.ZodString;
     show: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
     match: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     ifEmpty: z.ZodOptional<z.ZodString>;
@@ -133,8 +133,8 @@ declare const httpSchema: z.ZodObject<{
             }>;
             description: z.ZodString;
             in: z.ZodEnum<{
-                path: "path";
                 body: "body";
+                path: "path";
                 query: "query";
             }>;
             name: z.ZodOptional<z.ZodString>;
@@ -286,9 +286,9 @@ declare const odataSchema: z.ZodObject<{
                 string: "string";
                 number: "number";
                 boolean: "boolean";
+                guid: "guid";
                 integer: "integer";
                 decimal: "decimal";
-                guid: "guid";
                 datetime: "datetime";
                 datetimeoffset: "datetimeoffset";
             }>;
@@ -302,9 +302,9 @@ declare const odataSchema: z.ZodObject<{
                 string: "string";
                 number: "number";
                 boolean: "boolean";
+                guid: "guid";
                 integer: "integer";
                 decimal: "decimal";
-                guid: "guid";
                 datetime: "datetime";
                 datetimeoffset: "datetimeoffset";
             }>;
@@ -328,9 +328,9 @@ declare const odataSchema: z.ZodObject<{
                 string: "string";
                 number: "number";
                 boolean: "boolean";
+                guid: "guid";
                 integer: "integer";
                 decimal: "decimal";
-                guid: "guid";
                 datetime: "datetime";
                 datetimeoffset: "datetimeoffset";
             }>;
@@ -344,9 +344,9 @@ declare const odataSchema: z.ZodObject<{
                 string: "string";
                 number: "number";
                 boolean: "boolean";
+                guid: "guid";
                 integer: "integer";
                 decimal: "decimal";
-                guid: "guid";
                 datetime: "datetime";
                 datetimeoffset: "datetimeoffset";
             }>;
@@ -472,8 +472,8 @@ declare const eventsSchema: z.ZodObject<{
             click: z.ZodOptional<z.ZodArray<z.ZodString>>;
             clickUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
             siteRole: z.ZodOptional<z.ZodEnum<{
-                write: "write";
                 read: "read";
+                write: "write";
             }>>;
             agentCheck: z.ZodOptional<z.ZodBoolean>;
             confirm: z.ZodOptional<z.ZodString>;
@@ -531,7 +531,7 @@ declare const eventsSchema: z.ZodObject<{
         deliveryId: z.ZodArray<z.ZodString>;
         types: z.ZodArray<z.ZodObject<{
             type: z.ZodString;
-            same: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+            since: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -569,8 +569,8 @@ export declare const connectorSchema: z.ZodObject<{
         click: z.ZodOptional<z.ZodArray<z.ZodString>>;
         clickUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
         siteRole: z.ZodOptional<z.ZodEnum<{
-            write: "write";
             read: "read";
+            write: "write";
         }>>;
         agentCheck: z.ZodOptional<z.ZodBoolean>;
         confirm: z.ZodOptional<z.ZodString>;
@@ -586,6 +586,7 @@ export declare const connectorSchema: z.ZodObject<{
             field: z.ZodString;
             value: z.ZodString;
         }, z.core.$strict>>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     afterConnect: z.ZodArray<z.ZodObject<{
         title: z.ZodString;
@@ -604,8 +605,8 @@ export declare const connectorSchema: z.ZodObject<{
         click: z.ZodOptional<z.ZodArray<z.ZodString>>;
         clickUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
         siteRole: z.ZodOptional<z.ZodEnum<{
-            write: "write";
             read: "read";
+            write: "write";
         }>>;
         agentCheck: z.ZodOptional<z.ZodBoolean>;
         confirm: z.ZodOptional<z.ZodString>;
@@ -621,6 +622,7 @@ export declare const connectorSchema: z.ZodObject<{
             field: z.ZodString;
             value: z.ZodString;
         }, z.core.$strict>>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     fields: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -638,6 +640,7 @@ export declare const connectorSchema: z.ZodObject<{
             field: z.ZodString;
             value: z.ZodString;
         }, z.core.$strict>>;
+        optional: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     capabilities: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -686,8 +689,8 @@ export declare const connectorSchema: z.ZodObject<{
             click: z.ZodOptional<z.ZodArray<z.ZodString>>;
             clickUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
             siteRole: z.ZodOptional<z.ZodEnum<{
-                write: "write";
                 read: "read";
+                write: "write";
             }>>;
             agentCheck: z.ZodOptional<z.ZodBoolean>;
             confirm: z.ZodOptional<z.ZodString>;
@@ -734,6 +737,7 @@ export declare const connectorSchema: z.ZodObject<{
         path: z.ZodString;
         label: z.ZodString;
         show: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
         match: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
         body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         ifEmpty: z.ZodOptional<z.ZodString>;
@@ -750,6 +754,7 @@ export declare const connectorSchema: z.ZodObject<{
         path: z.ZodString;
         label: z.ZodString;
         show: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
         match: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
         body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         ifEmpty: z.ZodOptional<z.ZodString>;
@@ -806,8 +811,8 @@ export declare const connectorSchema: z.ZodObject<{
                 }>;
                 description: z.ZodString;
                 in: z.ZodEnum<{
-                    path: "path";
                     body: "body";
+                    path: "path";
                     query: "query";
                 }>;
                 name: z.ZodOptional<z.ZodString>;
@@ -956,9 +961,9 @@ export declare const connectorSchema: z.ZodObject<{
                     string: "string";
                     number: "number";
                     boolean: "boolean";
+                    guid: "guid";
                     integer: "integer";
                     decimal: "decimal";
-                    guid: "guid";
                     datetime: "datetime";
                     datetimeoffset: "datetimeoffset";
                 }>;
@@ -972,9 +977,9 @@ export declare const connectorSchema: z.ZodObject<{
                     string: "string";
                     number: "number";
                     boolean: "boolean";
+                    guid: "guid";
                     integer: "integer";
                     decimal: "decimal";
-                    guid: "guid";
                     datetime: "datetime";
                     datetimeoffset: "datetimeoffset";
                 }>;
@@ -998,9 +1003,9 @@ export declare const connectorSchema: z.ZodObject<{
                     string: "string";
                     number: "number";
                     boolean: "boolean";
+                    guid: "guid";
                     integer: "integer";
                     decimal: "decimal";
-                    guid: "guid";
                     datetime: "datetime";
                     datetimeoffset: "datetimeoffset";
                 }>;
@@ -1014,9 +1019,9 @@ export declare const connectorSchema: z.ZodObject<{
                     string: "string";
                     number: "number";
                     boolean: "boolean";
+                    guid: "guid";
                     integer: "integer";
                     decimal: "decimal";
-                    guid: "guid";
                     datetime: "datetime";
                     datetimeoffset: "datetimeoffset";
                 }>;
@@ -1139,8 +1144,8 @@ export declare const connectorSchema: z.ZodObject<{
                 click: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 clickUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
                 siteRole: z.ZodOptional<z.ZodEnum<{
-                    write: "write";
                     read: "read";
+                    write: "write";
                 }>>;
                 agentCheck: z.ZodOptional<z.ZodBoolean>;
                 confirm: z.ZodOptional<z.ZodString>;
@@ -1198,7 +1203,7 @@ export declare const connectorSchema: z.ZodObject<{
             deliveryId: z.ZodArray<z.ZodString>;
             types: z.ZodArray<z.ZodObject<{
                 type: z.ZodString;
-                same: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+                since: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
@@ -1233,8 +1238,8 @@ export declare const providerSchema: z.ZodObject<{
         click: z.ZodOptional<z.ZodArray<z.ZodString>>;
         clickUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
         siteRole: z.ZodOptional<z.ZodEnum<{
-            write: "write";
             read: "read";
+            write: "write";
         }>>;
         agentCheck: z.ZodOptional<z.ZodBoolean>;
         confirm: z.ZodOptional<z.ZodString>;
@@ -1286,8 +1291,8 @@ export declare const providerSchema: z.ZodObject<{
         click: z.ZodOptional<z.ZodArray<z.ZodString>>;
         clickUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
         siteRole: z.ZodOptional<z.ZodEnum<{
-            write: "write";
             read: "read";
+            write: "write";
         }>>;
         agentCheck: z.ZodOptional<z.ZodBoolean>;
         confirm: z.ZodOptional<z.ZodString>;
@@ -1308,14 +1313,16 @@ export declare const providerSchema: z.ZodObject<{
     revoke: z.ZodString;
 }, z.core.$strict>;
 export type Provider = z.infer<typeof providerSchema>;
+/** What a module's `create` is given: its connector.json, parsed and with the branding
+ *  filled in. Built-in apps get more (BuiltinContext, in the server). */
+export type ConnectorContext = {
+    connector: Connector;
+};
 /** The code behind one connector: its vendor client and its tools. */
-export type ConnectorModule = {
+export type ConnectorModule<Context extends ConnectorContext = ConnectorContext> = {
     id: string;
     connector?: ConnectorJson;
-    create(ctx: {
-        microsoft: MicrosoftClient;
-        connector: Connector;
-    }): {
+    create(ctx: Context): {
         vendor: Vendor;
         toolset: Toolset;
     };
@@ -1324,7 +1331,8 @@ export type ConnectorModule = {
 export declare const CONNECTORS_DIR: import("node:url").URL;
 /** A definition given inline rather than in a folder, checked as loadConnectors checks one. */
 export declare const parseConnector: (raw: unknown, where: string) => Connector;
-export declare function loadConnectors(dir?: import("node:url").URL): Connector[];
+/** `only`: the folder ids to read, so an app not offered is never parsed. */
+export declare function loadConnectors(dir?: import("node:url").URL, only?: (id: string) => boolean): Connector[];
 export declare function loadProviders(dir?: import("node:url").URL): Provider[];
 /** The ids of an app's choice fields: what its connection keeps from the admin's form. */
 export declare const choiceFields: (connector: Connector) => string[];
@@ -1343,4 +1351,6 @@ export declare function effectiveCapabilities(connector: Connector, grant: reado
 export declare function providerSettings(connectors: Connector[], provider: string): Map<string, Setting>;
 export declare function expandCopy(lines: string[], scopes: string[]): string;
 export declare function pickDisplay(data: unknown, path: string, match?: Record<string, unknown>): string[];
+/** Each value `show` picks, with its label `name` picks from the same list item. */
+export declare function pickLabels(data: unknown, show: string, name: string, match?: Record<string, unknown>): Record<string, string>;
 export {};

package/dist/packages/connector-kit/src/connector.js

@@ -74,6 +74,12 @@ const clickRule = [
 ];
 export const setupStep = stepSchema.refine(...clickRule);
 const step = setupStep;
+// An app's own setup step, which may be shown only while one of `capabilities` is ticked
+// (e.g. a script only saved searches need).
+const appStep = stepSchema
+    .extend({ capabilities: z.array(slug).min(1).optional() })
+    .strict()
+    .refine(...clickRule);
 const agentStep = agentStepSchema.refine(...clickRule);
 // A field with `options` is a choice (the first is the default), stored in the app's config
 // under its id. An option's `scopes` are vendor permissions the app then needs too, e.g.
@@ -92,6 +98,8 @@ const fieldSchema = z
     // Asked only while an earlier choice is this option; otherwise a choice's first option
     // holds and a text field is not asked (e.g. a password only for that sign-in method).
     requires: chosenSchema.optional(),
+    // May be left empty.
+    optional: z.boolean().default(false),
 })
     .strict();
 // "map": one optional value per value of the list limit `keys`, e.g. a folder per site.
@@ -110,19 +118,27 @@ const limitSchema = z
     .refine((l) => (l.kind === "map") === Boolean(l.keys), {
     message: "A map limit names the list limit it is keyed by (keys), and only it",
 });
+// The path up to and including its last list (`items[]` of `items[].id`), or "" without one.
+const listPrefix = (path) => path.includes("[]") ? path.slice(0, path.lastIndexOf("[]") + 2) : "";
 const httpProbeSchema = z
     .object({
     method: z.enum(["GET", "POST"]),
     path: z.string().startsWith("/"),
     label: text,
     show: text,
+    // Each value's label for the admin, read from the same list item as `show` (e.g. show
+    // "items[].id", name "items[].name").
+    name: text.optional(),
     // Keeps only list items whose fields equal these values, e.g. objects agents can query.
     match: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
     body: z.record(z.string(), z.unknown()).optional(),
     // Shown to the admin when the probe finds nothing, e.g. a missing project permission.
     ifEmpty: text.optional(),
 })
-    .strict();
+    .strict()
+    .refine((p) => !p.name || listPrefix(p.name) === listPrefix(p.show), {
+    message: "A probe's name is read from the same list as its show",
+});
 // A check no single API call answers, e.g. the permissions inside a token. The vendor client
 // implements it under this name (Vendor.checks).
 const vendorProbeSchema = z
@@ -663,7 +679,9 @@ const eventsSchema = z
     // the cursor, rounded up, plus one) {cursor} and {filter} (the subscription's filter put
     // into `filter`'s {value}, or nothing); `items` the list in the answer, each kept under
     // `wrap` so the webhook's paths fit; `cursor` the item's change time; `deliveryId` the
-    // paths joined into an id; `types` the first whose `same` paths are equal (or that has none).
+    // paths joined into an id; `types` the first whose `since` time is after the cursor the poll
+    // started from (or that has none): a record created since the last poll is new, whatever
+    // its change time says (Jira stamps an issue's update just after its creation).
     poll: z
         .object({
         request: eventRequest,
@@ -673,7 +691,7 @@ const eventsSchema = z
         cursor: eventPath,
         deliveryId: z.array(eventPath).min(1),
         types: z
-            .array(z.object({ type: eventId, same: z.tuple([eventPath, eventPath]).optional() }).strict())
+            .array(z.object({ type: eventId, since: eventPath.optional() }).strict())
             .min(1),
     })
         .strict()
@@ -710,8 +728,8 @@ export const connectorSchema = z
     // Vendor scopes every ceiling needs, whatever is ticked (e.g. what adding agents' Teams
     // bots takes), filled into {scope}/{scopes} with the capabilities' own.
     scopes: z.array(text).optional(),
-    setup: z.array(step),
-    afterConnect: z.array(step),
+    setup: z.array(appStep),
+    afterConnect: z.array(appStep),
     fields: z.array(fieldSchema),
     capabilities: z
         .array(z
@@ -848,6 +866,7 @@ export const connectorSchema = z
     return ([...c.setup, ...c.afterConnect].every((s) => !s.option || isOption(s.option, c.fields)) &&
         c.fields.every((f, i) => !f.requires || isOption(f.requires, c.fields.slice(0, i))));
 }, { message: "A step's option and a field's requires name an option of an earlier choice" })
+    .refine((c) => [...c.setup, ...c.afterConnect].every((s) => !s.capabilities || s.capabilities.every((id) => c.capabilities.some((x) => x.id === id))), { message: "A step's capabilities name capabilities of its connector" })
     .refine((c) => c.provider !== undefined || c.fields.length > 0, {
     message: "A guided connector needs connect form fields",
 })
@@ -921,7 +940,7 @@ export const providerSchema = z
     // The service can make a key pair whose certificate the admin uploads to their app.
     certificate: z.boolean(),
     setup: z.array(step),
-    fields: z.array(fieldSchema.extend({ optional: z.boolean().default(false) }).strict()).min(1),
+    fields: z.array(fieldSchema).min(1),
     // What one more agent needs outside the service (e.g. its mailbox), shown when its API key is
     // made with one of the apps each step names.
     addAgent: z.array(agentStep).default([]),
@@ -947,9 +966,9 @@ function parse(raw, where, schema) {
 export const parseConnector = (raw, where) => parse(raw, where, connectorSchema);
 // Each subfolder of dir holding `file` is one definition, whose id is the folder's name.
 // Subfolders may be links: Kubernetes mounts ConfigMap and Secret folders that way.
-function loadDir(dir, file, schema) {
+function loadDir(dir, file, schema, only = () => true) {
     return readdirSync(dir)
-        .filter((name) => existsSync(new URL(`${name}/${file}`, dir)))
+        .filter((name) => only(name) && existsSync(new URL(`${name}/${file}`, dir)))
         .sort()
         .map((name) => {
         const where = `${name}/${file}`;
@@ -959,8 +978,9 @@ function loadDir(dir, file, schema) {
         return data;
     });
 }
-export function loadConnectors(dir = CONNECTORS_DIR) {
-    return loadDir(dir, "connector.json", connectorSchema);
+/** `only`: the folder ids to read, so an app not offered is never parsed. */
+export function loadConnectors(dir = CONNECTORS_DIR, only) {
+    return loadDir(dir, "connector.json", connectorSchema, only);
 }
 export function loadProviders(dir = CONNECTORS_DIR) {
     return loadDir(dir, "provider.json", providerSchema);
@@ -1019,6 +1039,25 @@ export function expandCopy(lines, scopes) {
 }
 // Reads `a.b` / `values[].name` paths out of a JSON response for display.
 export function pickDisplay(data, path, match = {}) {
+    return pick(data, path, match)
+        .filter((v) => v !== undefined && v !== null)
+        .map(String);
+}
+/** Each value `show` picks, with its label `name` picks from the same list item. */
+export function pickLabels(data, show, name, match = {}) {
+    const prefix = listPrefix(show);
+    const items = prefix ? pick(data, prefix, match) : [data];
+    const rest = (path) => path.slice(prefix.length).replace(/^\./, "");
+    const out = {};
+    for (const item of items) {
+        const [value] = rest(show) ? pick(item, rest(show)) : [item];
+        const [label] = rest(name) ? pick(item, rest(name)) : [item];
+        if (value != null && label != null)
+            out[String(value)] = String(label);
+    }
+    return out;
+}
+function pick(data, path, match = {}) {
     const matches = (v) => Object.entries(match).every(([k, want]) => v && typeof v === "object" && v[k] === want);
     let values = [data];
     for (const part of path.split(".")) {
@@ -1029,6 +1068,6 @@ export function pickDisplay(data, path, match = {}) {
             return many ? (Array.isArray(next) ? next.filter(matches) : []) : [next];
         });
     }
-    return values.filter((v) => v !== undefined && v !== null).map(String);
+    return values;
 }
 //# sourceMappingURL=connector.js.map