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

package/README.md

@@ -6,7 +6,8 @@ agent's grants and written to an audit log. Agents never hold the apps' credenti
 
 - **Built-in apps:** Jira, Microsoft 365 (Outlook mail and calendar, SharePoint files and Excel,
   Teams, Entra ID, Intune, Dynamics 365), Jamf Pro, Okta, Slack, Salesforce, Gong, SAP S/4HANA,
-  Oracle NetSuite, ServiceNow, Workday, FedEx, Dell TechDirect.
+  Oracle NetSuite, ServiceNow, Workday, FedEx, Dell TechDirect, GitLab, Argo CD, SonarQube,
+  Datadog, PagerDuty, Grafana, Zephyr Scale, Confluence.
 - **Your own apps without code:** describe an internal REST API or a SaaS app's in one
   `connector.json`, or draft one from its OpenAPI spec
   ([docs/http-connector.md](docs/http-connector.md)); a SOAP service
@@ -24,7 +25,8 @@ agent's grants and written to an audit log. Agents never hold the apps' credenti
   your own admin pages.
 
 How it is secured: [docs/security.md](docs/security.md). Adding apps:
-[docs/connectors.md](docs/connectors.md).
+[docs/connectors.md](docs/connectors.md). Running it next to internal systems (your own
+certificate authority, a proxy in front): [docs/inside-your-network.md](docs/inside-your-network.md).
 
 ## Quick start (about 10 minutes)
 
@@ -142,7 +144,8 @@ serve({ fetch: eac.fetch, port: 3000 });
 ```
 
 **The typed admin client.** The admin API refuses requests that came through a load balancer
-(`X-Forwarded-For`), so call it from your server, over the network or in the same process:
+(`X-Forwarded-For`), so call it from your server, over the network or in the same process
+(behind a proxy: [docs/inside-your-network.md](docs/inside-your-network.md)):
 
 ```ts
 import { createClient } from "@arbium/enterprise-agent-connect-client";
@@ -183,8 +186,13 @@ const orders: ConnectorJson = {
 };
 ```
 
+**Your own app, per organization.** Each organization can add its own apps through the admin
+API, as many as it wants, without a restart: see [Add internal apps through the admin
+API](docs/http-connector.md#add-internal-apps-through-the-admin-api).
+
 **Your own app, as code.** Build a `ConnectorModule` on the connector kit and give it its
-definition as `connector` ([docs/connectors.md](docs/connectors.md)):
+definition as `connector` ([docs/connectors.md](docs/connectors.md)). `create` gets a
+`ConnectorContext`, `{ connector }`: the definition parsed, with the branding filled in.
 
 ```ts
 import { z } from "zod";
@@ -231,7 +239,9 @@ built-in app is offered. Apps you add with `CONNECTOR_DIRS` are always offered.
 `deploy/helm/agent-connect` is a small chart: one replica (Teams and app event run limits are
 counted in one process), a Service, and an optional Ingress with only the public paths. It needs the image
 (`image.repository`, `image.tag`; releases are `ghcr.io/try-caret/enterprise-agent-connect:<version>`) and a Secret with `DATABASE_URL`, `CONNECT_ENCRYPTION_KEY`
-and `AGENT_CONNECT_ADMIN_TOKEN` (`existingSecret`).
+and `AGENT_CONNECT_ADMIN_TOKEN` (`existingSecret`). For apps whose certificates your own
+authority signed, name a ConfigMap or Secret holding its bundle in `caBundle`
+([docs/inside-your-network.md](docs/inside-your-network.md)).
 
 ## Layout
 
@@ -239,12 +249,14 @@ and `AGENT_CONNECT_ADMIN_TOKEN` (`existingSecret`).
   migrations) and its tests
 - `packages/connector-kit`: what a connector builds on (schemas, tool helpers, vendor types)
 - `packages/client`: typed admin API client
-- `connectors/<app>`: one folder per app: `connector.json`, `index.ts`, `tools.ts`, `vendor.ts`
+- `connectors/<app>`: one folder per app: `connector.json`, and for apps with code `index.ts`,
+  `tools.ts`, `vendor.ts`
 - `connectors/http`, `connectors/soap`, `connectors/odata`, `connectors/sql`: run any app
   described only in its `connector.json` (docs/http-connector.md, docs/soap-connector.md,
   docs/odata-connector.md, docs/sql-connector.md)
 - `examples/internal-app`: a small internal API and its connector, for the quick start
-- `scripts/openapi-to-connector.ts`: drafts an http connector from an OpenAPI 3.x spec
+- `scripts/openapi-to-connector.ts`: drafts an http connector from an OpenAPI 3.x spec (the
+  drafting itself is `connectors/http/openapi.ts`, also behind the admin API's internal app drafts)
 - `examples/legacy-apps`: a SOAP and an SAP OData connector, described only in JSON
 - `scripts/wsdl-to-connector.ts`, `scripts/odata-to-connector.ts`: draft a connector from a WSDL
   or an OData `$metadata`

package/dist/connectors/adestra/connector.json

@@ -0,0 +1,336 @@
+{
+  "id": "adestra",
+  "name": "Adestra",
+  "description": "Let agents draft email campaigns in Adestra: find projects and campaigns, write the subject line and content, and send the campaign to your approvers. Agents never launch a campaign to a list. For staging campaigns and invitations for people to review.",
+  "logo": "/brand/registry/adestra.svg",
+  "identity": "An Adestra API token. It acts as the Adestra user who created it, with that user's workspaces and access rights, so make a user for agents with only the workspaces they need.",
+  "accountKey": "host",
+  "connectionKind": "guided",
+  "setup": [
+    {
+      "title": "Make a user for agents",
+      "body": "An API token acts as the user who creates it. Make a separate Adestra user for agents, give it read and write API access and only the workspaces agents should draft in. Ask Adestra support to turn on API access for the user if the option is missing.",
+      "link": {
+        "label": "Adestra: API access and tokens",
+        "href": "https://app.adestra.com/doc/page/current/index/api"
+      }
+    },
+    {
+      "title": "Create an API token",
+      "body": "Sign in to Adestra as the agents' user. You can test the token with the command below: it shows the user the token belongs to and changes nothing.",
+      "click": [
+        "Select your user icon in the title bar to open your user panel.",
+        "Select Manage API tokens.",
+        "Press Create new API token, enter a name such as Agents and, if you like, a description.",
+        "Press Create and copy the new token."
+      ],
+      "copy": [
+        "curl -s -H \"Authorization: TOKEN $ADESTRA_TOKEN\" https://app.adestra.com/api/rest/1/users/self"
+      ],
+      "shell": "bash"
+    }
+  ],
+  "afterConnect": [],
+  "fields": [{ "id": "api_token", "label": "API token", "secret": true }],
+  "capabilities": [
+    {
+      "id": "read_campaigns",
+      "label": "Read campaigns",
+      "description": "Find projects and campaigns, and read a campaign's details, options such as the subject line and sender, and its HTML or text content.",
+      "required": true,
+      "note": "Reaches every project and campaign the agents' user can see, unless you keep a key to chosen projects under API keys. Read-only.",
+      "scopes": [],
+      "permissions": [],
+      "tools": [
+        "adestra_list_projects",
+        "adestra_search_campaigns",
+        "adestra_get_campaign",
+        "adestra_get_campaign_options",
+        "adestra_get_message"
+      ]
+    },
+    {
+      "id": "draft_campaigns",
+      "label": "Draft campaigns",
+      "description": "Create campaigns, rename them or change their list, set options such as the subject line and sender, and write their HTML or text content.",
+      "note": "Can change any campaign the agents' user can edit, including ones people wrote. Nothing here launches a campaign.",
+      "scopes": [],
+      "permissions": [],
+      "tools": [
+        "adestra_create_campaign",
+        "adestra_update_campaign",
+        "adestra_set_campaign_option",
+        "adestra_set_message"
+      ]
+    },
+    {
+      "id": "request_approval",
+      "label": "Ask for approval",
+      "description": "Send a campaign to one of your Adestra approval groups for review.",
+      "note": "Approvers decide whether it is launched. Agents cannot ask for it to be launched once approved.",
+      "scopes": [],
+      "permissions": [],
+      "tools": ["adestra_request_approval"]
+    },
+    {
+      "id": "send_tests",
+      "label": "Send test emails",
+      "description": "Email a test of a campaign to chosen addresses.",
+      "destructive": true,
+      "note": "A test is a real email. Keep a key to your own team's addresses under API keys.",
+      "scopes": [],
+      "permissions": [],
+      "tools": ["adestra_send_test"]
+    }
+  ],
+  "limits": [
+    {
+      "id": "projects",
+      "label": "Projects",
+      "help": "Optional: only these Adestra projects (their ids) when finding and creating campaigns and reading a campaign's details. A campaign's options and content, and changes to a campaign by its id, are not checked against this. Leave empty for every project.",
+      "kind": "list",
+      "required": false,
+      "pattern": "^\\d{1,12}$"
+    },
+    {
+      "id": "test_addresses",
+      "label": "Test email addresses",
+      "help": "Optional: the only addresses tests may be sent to. Leave empty for any address.",
+      "kind": "list",
+      "required": false,
+      "pattern": "^[^@\\s]+@[^@\\s]+$"
+    }
+  ],
+  "verify": {
+    "method": "GET",
+    "path": "/users/self",
+    "label": "Adestra user",
+    "show": "email"
+  },
+  "discover": {
+    "method": "GET",
+    "path": "/projects",
+    "label": "Projects",
+    "show": "projects[].id",
+    "name": "projects[].name"
+  },
+  "revoke": "In Adestra, open the agents' user panel, select Manage API tokens and delete the token. Agents lose access to Adestra at once.",
+  "http": {
+    "baseUrl": "https://app.adestra.com/api/rest/1",
+    "auth": { "type": "header", "header": "Authorization", "prefix": "TOKEN ", "value": "api_token" },
+    "tools": [
+      {
+        "name": "adestra_list_projects",
+        "description": "List Adestra projects (which hold campaigns), or only those in one workspace or with a name.",
+        "method": "GET",
+        "path": "/projects",
+        "params": {
+          "workspace_id": {
+            "type": "integer",
+            "description": "Only projects in this workspace",
+            "in": "query",
+            "name": "search:workspace_id",
+            "required": false
+          },
+          "name": {
+            "type": "string",
+            "description": "Only projects with exactly this name",
+            "in": "query",
+            "name": "search:name",
+            "required": false
+          },
+          "page": {
+            "type": "integer",
+            "description": "Page of results, from 1 (250 per page)",
+            "in": "query",
+            "name": "paging:page",
+            "required": false
+          }
+        },
+        "result": { "items": "projects", "fields": ["id", "name", "description", "workspace_id"] }
+      },
+      {
+        "name": "adestra_search_campaigns",
+        "description": "Find campaigns in a project, by name, or by whether they were launched.",
+        "method": "GET",
+        "path": "/campaigns",
+        "params": {
+          "project_id": {
+            "type": "integer",
+            "description": "Only campaigns in this project",
+            "in": "query",
+            "name": "search:project_id",
+            "required": false,
+            "limit": "projects"
+          },
+          "name": {
+            "type": "string",
+            "description": "Only campaigns with exactly this name",
+            "in": "query",
+            "name": "search:name",
+            "required": false
+          },
+          "launched": {
+            "type": "boolean",
+            "description": "Only launched (true) or not yet launched (false) campaigns",
+            "in": "query",
+            "name": "search:launched",
+            "required": false
+          },
+          "page": {
+            "type": "integer",
+            "description": "Page of results, from 1",
+            "in": "query",
+            "name": "paging:page",
+            "required": false
+          },
+          "page_size": {
+            "type": "integer",
+            "description": "Results per page, up to 250",
+            "in": "query",
+            "name": "paging:page_size",
+            "default": 50
+          }
+        },
+        "result": {
+          "items": "campaigns",
+          "fields": ["id", "name", "description", "project_id", "list_id", "subject_line", "published", "launched", "edited_date"]
+        }
+      },
+      {
+        "name": "adestra_get_campaign",
+        "description": "Read one campaign: name, project, list, subject line and whether it was published or launched.",
+        "method": "GET",
+        "path": "/campaigns/{campaign_id}",
+        "params": {
+          "campaign_id": { "type": "integer", "description": "The campaign id", "in": "path" }
+        },
+        "answerLimits": [{ "field": "project_id", "limit": "projects" }]
+      },
+      {
+        "name": "adestra_get_campaign_options",
+        "description": "Read a campaign's options, such as subject line, sender and reply names and addresses, and unsubscribe list.",
+        "method": "GET",
+        "path": "/campaigns/{campaign_id}/options",
+        "params": {
+          "campaign_id": { "type": "integer", "description": "The campaign id", "in": "path" }
+        }
+      },
+      {
+        "name": "adestra_get_message",
+        "description": "Read a campaign's HTML or text content.",
+        "method": "GET",
+        "path": "/campaigns/{campaign_id}/message/{type}",
+        "params": {
+          "campaign_id": { "type": "integer", "description": "The campaign id", "in": "path" },
+          "type": { "type": "string", "enum": ["html", "text"], "description": "Which part: html or text", "in": "path" }
+        }
+      },
+      {
+        "name": "adestra_create_campaign",
+        "description": "Create a campaign in a project. It is not launched; set its options and content next.",
+        "method": "POST",
+        "path": "/campaigns",
+        "params": {
+          "name": { "type": "string", "description": "Campaign name, up to 255 bytes", "in": "body" },
+          "project_id": {
+            "type": "integer",
+            "description": "The project to create it in",
+            "in": "body",
+            "limit": "projects"
+          },
+          "description": { "type": "string", "description": "What the campaign is for", "in": "body", "required": false },
+          "list_id": { "type": "integer", "description": "The list it will go to", "in": "body", "required": false },
+          "apply_user_defaults": {
+            "type": "boolean",
+            "description": "Apply the user's campaign preferences and presets",
+            "in": "query",
+            "name": "options:apply_user_defaults",
+            "default": true
+          }
+        },
+        "result": { "fields": ["id", "name", "project_id", "list_id"] }
+      },
+      {
+        "name": "adestra_update_campaign",
+        "description": "Rename a campaign, change its description or the list it will go to. Values left out stay as they are.",
+        "method": "PUT",
+        "path": "/campaigns/{campaign_id}",
+        "params": {
+          "campaign_id": { "type": "integer", "description": "The campaign id", "in": "path" },
+          "name": { "type": "string", "description": "New name", "in": "body", "required": false },
+          "description": { "type": "string", "description": "New description", "in": "body", "required": false },
+          "list_id": { "type": "integer", "description": "New list id", "in": "body", "required": false }
+        },
+        "result": { "fields": ["id", "name", "project_id", "list_id"] }
+      },
+      {
+        "name": "adestra_set_campaign_option",
+        "description": "Set the campaign's subject line, sender name or reply name.",
+        "method": "PUT",
+        "path": "/campaigns/{campaign_id}/options",
+        "params": {
+          "campaign_id": { "type": "integer", "description": "The campaign id", "in": "path" },
+          "name": {
+            "type": "string",
+            "description": "Which option",
+            "in": "body",
+            "enum": ["subject_line", "from_name", "reply_name"]
+          },
+          "value": { "type": "string", "description": "Option value", "in": "body" }
+        }
+      },
+      {
+        "name": "adestra_set_message",
+        "description": "Write a campaign's HTML or text content, replacing what is there.",
+        "method": "PUT",
+        "path": "/campaigns/{campaign_id}/message/{type}",
+        "params": {
+          "campaign_id": { "type": "integer", "description": "The campaign id", "in": "path" },
+          "type": { "type": "string", "enum": ["html", "text"], "description": "Which part: html or text", "in": "path" },
+          "content": { "type": "string", "description": "The HTML or text content", "in": "body" }
+        },
+        "result": { "fields": ["campaign_id", "type"] }
+      },
+      {
+        "name": "adestra_request_approval",
+        "description": "Send a campaign to an approval group for review. Approvers are told when notify_approvers is true.",
+        "method": "POST",
+        "path": "/campaigns/{campaign_id}/request_approval/{approval_group_id}",
+        "params": {
+          "campaign_id": { "type": "integer", "description": "The campaign id", "in": "path" },
+          "approval_group_id": { "type": "integer", "description": "The approval group's id", "in": "path" },
+          "threshold": {
+            "type": "integer",
+            "description": "Approvals needed; left out, everyone in the group must approve",
+            "in": "body",
+            "required": false
+          },
+          "notify_approvers": {
+            "type": "boolean",
+            "description": "Email the group's members about the request",
+            "in": "body",
+            "default": true
+          }
+        }
+      },
+      {
+        "name": "adestra_send_test",
+        "description": "Email a test of a campaign to one or more addresses.",
+        "method": "POST",
+        "path": "/campaigns/{campaign_id}/send_test",
+        "destructive": true,
+        "params": {
+          "campaign_id": { "type": "integer", "description": "The campaign id", "in": "path" },
+          "emails": {
+            "type": "array",
+            "items": "string",
+            "description": "Addresses to send the test to",
+            "in": "body",
+            "limit": "test_addresses"
+          }
+        }
+      }
+    ]
+  }
+}

package/dist/connectors/adobe-admin-console/connector.json

@@ -0,0 +1,212 @@
+{
+  "id": "adobe-admin-console",
+  "name": "Adobe Admin Console",
+  "description": "Let agents read who has which Adobe licences: your Adobe users, the product profiles and user groups they are in, and who is in a profile or group. For joiner, mover and leaver access requests.",
+  "logo": "/brand/registry/adobe-admin-console.svg",
+  "identity": "An Adobe Developer Console project with the User Management API and OAuth Server-to-Server credentials. Adobe gives these credentials full user management, so agents here only read.",
+  "accountKey": "organization",
+  "connectionKind": "guided",
+  "setup": [
+    {
+      "title": "Create a project with the User Management API",
+      "body": "You need an Adobe system administrator. Adobe gives the project's credentials full user management for your organization; this app only ever reads with them.",
+      "link": {
+        "label": "Adobe: User Management API authentication",
+        "href": "https://adobe-apiplatform.github.io/umapi-documentation/en/UM_Authentication.html"
+      },
+      "click": [
+        "In Adobe Developer Console (developer.adobe.com/console), create a new project.",
+        "Select Add API, choose User Management API under Adobe Services, and select Next.",
+        "Choose OAuth Server-to-Server, then Save configured API."
+      ]
+    },
+    {
+      "title": "Copy the credentials",
+      "body": "Copy the three values for the form below. Give each agent the same Organization ID under API keys too: agents name it in every call, and only that organization is allowed.",
+      "click": [
+        "In the project, open the OAuth Server-to-Server credential.",
+        "Copy the Client ID and, after Retrieve client secret, the Client Secret.",
+        "Copy the Organization ID, which ends in @AdobeOrg."
+      ]
+    }
+  ],
+  "afterConnect": [],
+  "fields": [
+    {
+      "id": "organization",
+      "label": "Organization ID",
+      "help": "From the OAuth Server-to-Server credential, ending in @AdobeOrg.",
+      "placeholder": "12345ABC67890@AdobeOrg",
+      "secret": false
+    },
+    {
+      "id": "client_id",
+      "label": "Client ID",
+      "secret": false
+    },
+    {
+      "id": "client_secret",
+      "label": "Client Secret",
+      "secret": true
+    }
+  ],
+  "capabilities": [
+    {
+      "id": "read",
+      "label": "Read users and licences",
+      "description": "Read a user by email with the product profiles and groups they are in, list users, list product profiles and user groups with their product and licence quota, and list who is in a profile or group.",
+      "required": true,
+      "note": "Reaches every user in the organization. Read-only.",
+      "scopes": [],
+      "permissions": [],
+      "tools": [
+        "adobe_get_user",
+        "adobe_list_users",
+        "adobe_list_groups",
+        "adobe_list_group_members"
+      ]
+    }
+  ],
+  "limits": [
+    {
+      "id": "organizations",
+      "label": "Organization ID",
+      "help": "The Adobe Organization ID from the connect form, ending in @AdobeOrg. Agents can reach only this organization.",
+      "kind": "list",
+      "required": true,
+      "pattern": "^[A-Za-z0-9]+@AdobeOrg$"
+    }
+  ],
+  "verify": {
+    "method": "GET",
+    "path": "/groups/{organization}/0",
+    "label": "Adobe product profiles and groups",
+    "show": "groups[].groupName"
+  },
+  "revoke": "In Adobe Developer Console, open the project and delete the OAuth Server-to-Server credential, or the project. Agents lose access to Adobe at once.",
+  "http": {
+    "baseUrl": "https://usermanagement.adobe.io/v2/usermanagement",
+    "auth": {
+      "type": "oauth2",
+      "tokenUrl": "https://ims-na1.adobelogin.com/ims/token/v3",
+      "clientId": "client_id",
+      "clientSecret": "client_secret",
+      "scope": "openid,AdobeID,user_management_sdk"
+    },
+    "fieldHeaders": {
+      "x-api-key": "client_id"
+    },
+    "tools": [
+      {
+        "name": "adobe_get_user",
+        "description": "Read one Adobe user by email: name, status, account type and the product profiles, user groups and admin groups they are in.",
+        "method": "GET",
+        "path": "/organizations/{org_id}/users/{email}",
+        "params": {
+          "org_id": {
+            "type": "string",
+            "description": "The Adobe Organization ID, ending in @AdobeOrg",
+            "in": "path",
+            "limit": "organizations"
+          },
+          "email": {
+            "type": "string",
+            "description": "The user's full email address",
+            "in": "path"
+          }
+        }
+      },
+      {
+        "name": "adobe_list_users",
+        "description": "List the organization's users a page at a time: email, name, status, account type and groups. Pages start at 0; lastPage true marks the last.",
+        "method": "GET",
+        "path": "/users/{org_id}/{page}",
+        "params": {
+          "org_id": {
+            "type": "string",
+            "description": "The Adobe Organization ID, ending in @AdobeOrg",
+            "in": "path",
+            "limit": "organizations"
+          },
+          "page": {
+            "type": "integer",
+            "description": "The page, starting at 0",
+            "in": "path"
+          }
+        },
+        "result": {
+          "fields": [
+            "lastPage",
+            "users.email",
+            "users.firstname",
+            "users.lastname",
+            "users.status",
+            "users.type",
+            "users.groups"
+          ]
+        }
+      },
+      {
+        "name": "adobe_list_groups",
+        "description": "List product profiles, user groups and admin groups a page at a time: name, type, member count, and for a product profile its product and licence quota. Pages start at 0; lastPage true marks the last.",
+        "method": "GET",
+        "path": "/groups/{org_id}/{page}",
+        "params": {
+          "org_id": {
+            "type": "string",
+            "description": "The Adobe Organization ID, ending in @AdobeOrg",
+            "in": "path",
+            "limit": "organizations"
+          },
+          "page": {
+            "type": "integer",
+            "description": "The page, starting at 0",
+            "in": "path"
+          }
+        }
+      },
+      {
+        "name": "adobe_list_group_members",
+        "description": "List who is in one product profile, user group or admin group, a page at a time. Pages start at 0; lastPage true marks the last.",
+        "method": "GET",
+        "path": "/users/{org_id}/{page}/{group}",
+        "params": {
+          "org_id": {
+            "type": "string",
+            "description": "The Adobe Organization ID, ending in @AdobeOrg",
+            "in": "path",
+            "limit": "organizations"
+          },
+          "page": {
+            "type": "integer",
+            "description": "The page, starting at 0",
+            "in": "path"
+          },
+          "group": {
+            "type": "string",
+            "description": "The product profile, user group or admin group name",
+            "in": "path"
+          },
+          "exclude_groups": {
+            "type": "boolean",
+            "description": "true to leave out each member's own list of groups",
+            "in": "query",
+            "name": "excludeGroups",
+            "default": true
+          }
+        },
+        "result": {
+          "fields": [
+            "lastPage",
+            "groupName",
+            "users.email",
+            "users.firstname",
+            "users.lastname",
+            "users.status",
+            "users.type"
+          ]
+        }
+      }
+    ]
+  }
+}