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

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

@@ -1,7 +1,6 @@
 import { z } from "zod";
-import type { MicrosoftClient } from "../../../connectors/microsoft/client.js";
 import type { Toolset } from "./common.js";
-import type { Vendor } from "./types.js";
+import { type Vendor } from "./types.js";
 declare const settingSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
@@ -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>;
@@ -62,6 +62,13 @@ declare const probeSchema: z.ZodUnion<readonly [z.ZodObject<{
     ifEmpty: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>]>;
 export type Probe = z.infer<typeof probeSchema>;
+/** The connect form fields an address's placeholders name. */
+export declare function addressFields(address: string): string[];
+/** Refuses a filled-in address whose host is not one of `allowed` (when there is a list). */
+export declare function checkHost(url: URL, allowed: string[] | undefined): void;
+/** The address filled with the connection's values; a value that does not fit its place is
+ *  refused, so it can never move the call to another host or path. */
+export declare function fillAddress(address: string, config: Record<string, string>, label?: (id: string) => string): string;
 declare const httpAuthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"header">;
     header: z.ZodString;
@@ -80,6 +87,11 @@ declare const httpAuthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     clientId: z.ZodString;
     clientSecret: z.ZodString;
     scope: z.ZodOptional<z.ZodString>;
+    clientAuth: z.ZodOptional<z.ZodEnum<{
+        body: "body";
+        basic: "basic";
+    }>>;
+    audience: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"query">;
     param: z.ZodString;
@@ -87,7 +99,8 @@ declare const httpAuthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strict>], "type">;
 export type HttpAuth = z.infer<typeof httpAuthSchema>;
 declare const httpSchema: z.ZodObject<{
-    baseUrl: z.ZodURL;
+    baseUrl: z.ZodString;
+    allowedHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     auth: z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"header">;
         header: z.ZodString;
@@ -106,12 +119,18 @@ declare const httpSchema: z.ZodObject<{
         clientId: z.ZodString;
         clientSecret: z.ZodString;
         scope: z.ZodOptional<z.ZodString>;
+        clientAuth: z.ZodOptional<z.ZodEnum<{
+            body: "body";
+            basic: "basic";
+        }>>;
+        audience: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"query">;
         param: z.ZodString;
         value: z.ZodString;
     }, z.core.$strict>], "type">;
     headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    fieldHeaders: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     tools: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         description: z.ZodString;
@@ -133,8 +152,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>;
@@ -174,7 +193,7 @@ declare const httpSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type HttpApp = z.infer<typeof httpSchema>;
 declare const soapSchema: z.ZodObject<{
-    endpoint: z.ZodURL;
+    endpoint: z.ZodString;
     version: z.ZodDefault<z.ZodEnum<{
         1.1: "1.1";
         1.2: "1.2";
@@ -234,7 +253,8 @@ declare const soapSchema: z.ZodObject<{
 export type SoapApp = z.infer<typeof soapSchema>;
 export type SoapTool = SoapApp["tools"][number];
 declare const odataSchema: z.ZodObject<{
-    serviceRoot: z.ZodURL;
+    serviceRoot: z.ZodString;
+    allowedHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     version: z.ZodEnum<{
         2: "2";
         4: "4";
@@ -257,6 +277,11 @@ declare const odataSchema: z.ZodObject<{
         clientId: z.ZodString;
         clientSecret: z.ZodString;
         scope: z.ZodOptional<z.ZodString>;
+        clientAuth: z.ZodOptional<z.ZodEnum<{
+            body: "body";
+            basic: "basic";
+        }>>;
+        audience: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"query">;
         param: z.ZodString;
@@ -286,9 +311,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 +327,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 +353,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 +369,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 +497,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 +556,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 +594,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 +611,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 +630,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 +647,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 +665,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 +714,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 +762,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 +779,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>;
@@ -760,7 +790,8 @@ export declare const connectorSchema: z.ZodObject<{
     }, z.core.$strict>]>>;
     revoke: z.ZodString;
     http: z.ZodOptional<z.ZodObject<{
-        baseUrl: z.ZodURL;
+        baseUrl: z.ZodString;
+        allowedHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
         auth: z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"header">;
             header: z.ZodString;
@@ -779,12 +810,18 @@ export declare const connectorSchema: z.ZodObject<{
             clientId: z.ZodString;
             clientSecret: z.ZodString;
             scope: z.ZodOptional<z.ZodString>;
+            clientAuth: z.ZodOptional<z.ZodEnum<{
+                body: "body";
+                basic: "basic";
+            }>>;
+            audience: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"query">;
             param: z.ZodString;
             value: z.ZodString;
         }, z.core.$strict>], "type">;
         headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        fieldHeaders: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         tools: z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
@@ -806,8 +843,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>;
@@ -846,7 +883,7 @@ export declare const connectorSchema: z.ZodObject<{
         allowInsecureHttp: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     soap: z.ZodOptional<z.ZodObject<{
-        endpoint: z.ZodURL;
+        endpoint: z.ZodString;
         version: z.ZodDefault<z.ZodEnum<{
             1.1: "1.1";
             1.2: "1.2";
@@ -904,7 +941,8 @@ export declare const connectorSchema: z.ZodObject<{
         allowInsecureHttp: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     odata: z.ZodOptional<z.ZodObject<{
-        serviceRoot: z.ZodURL;
+        serviceRoot: z.ZodString;
+        allowedHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
         version: z.ZodEnum<{
             2: "2";
             4: "4";
@@ -927,6 +965,11 @@ export declare const connectorSchema: z.ZodObject<{
             clientId: z.ZodString;
             clientSecret: z.ZodString;
             scope: z.ZodOptional<z.ZodString>;
+            clientAuth: z.ZodOptional<z.ZodEnum<{
+                body: "body";
+                basic: "basic";
+            }>>;
+            audience: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"query">;
             param: z.ZodString;
@@ -956,9 +999,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 +1015,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 +1041,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 +1057,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 +1182,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 +1241,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 +1276,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 +1329,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 +1351,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 +1369,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 +1389,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 {};