@jskit-ai/connectors-catalog 0.1.1

package/src/shared/microsoft.js

@@ -0,0 +1,231 @@
+import { createSchema } from "json-rest-schema";
+
+function definition(id, name, description, permission, label, organizationOnly = false, verificationFields = []) {
+  const authority = organizationOnly ? "organizations" : "common";
+  const audiences = organizationOnly ? ["organizations"] : ["common", "organizations", "consumers"];
+  return Object.freeze({
+    id, name, description, verificationFields, categories: ["Microsoft", "Productivity"],
+    accountModes: ["shared", "per-user", "assistant"], authenticationMethods: ["oauth2"],
+    scopes: [
+      { value: permission, label, recommended: true },
+      { value: "offline_access", label: "Keep access when you are away", recommended: true }
+    ],
+    settingsSchema: createSchema({
+      tenantId: { type: "string", maxLength: 36, defaultTo: authority,
+        validator: (value) => audiences.includes(value) || /^[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}$/iu.test(value) ||
+          `Use ${audiences.join(", ")} or your Directory (tenant) ID as a GUID.` }
+    }),
+    settingsFields: [{ name: "tenantId", label: "Directory (tenant) ID", placeholder: authority,
+      hint: `Use ${authority} for the default audience, or the directory GUID for a single-tenant app. This is not the Application (client) ID.` }],
+    setup: {
+      url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+      steps: [
+        "In Microsoft Entra admin center, select the directory that owns your app. Open Entra ID > App registrations > New registration.",
+        organizationOnly
+          ? "Choose Multiple Entra ID tenants. This connector requires a work or school account."
+          : "Choose Any Entra ID Tenant + Personal Microsoft accounts for this connector's common sign-in endpoint.",
+        "For a single-tenant registration, choose Single tenant only and copy Directory (tenant) ID into this form. The selected audience must match your app registration.",
+        "Register the app. Under Authentication, add a Web platform with the exact callback URL served by your backend.",
+        `Under API permissions, add Microsoft Graph delegated ${permission} and offline_access permissions. Tenant policy may require administrator consent.`,
+        "Copy Application (client) ID into this form. Under Certificates & secrets, create a client secret and store its Value in the referenced Env variable.",
+        "Store the callback URL in its Env variable, then save configuration. The runtime requests consent and verifies the selected operation."
+      ]
+    }
+  });
+}
+
+const microsoftOutlookDefinition = Object.freeze({
+  ...definition("microsoft-outlook", "Microsoft Outlook", "Read messages and files, send text mail, manage read/folder state and calendar appointments.", "Mail.Read", "Read your mail"),
+  scopes: [
+    { value: "Mail.Read", label: "Read your mail", required: true, recommended: true },
+    { value: "Mail.ReadWrite", label: "Read and write your mail", recommended: true },
+    { value: "Mail.Send", label: "Send mail as you", recommended: true },
+    { value: "Mail.ReadBasic", label: "Read basic mail properties" },
+    { value: "Calendars.Read", label: "Read your calendars" },
+    { value: "Calendars.ReadWrite", label: "Read and write your calendars", recommended: true },
+    { value: "offline_access", label: "Keep access when you are away", recommended: true }
+  ],
+  setup: {
+    url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+    steps: [
+      "In Microsoft Entra admin center → Entra ID → App registrations → New registration, name the application. For common, choose accounts in any organizational directory and personal Microsoft accounts. For single tenant, choose this directory only and enter its Directory (tenant) ID. Select Register and copy Application (client) ID into Client ID.",
+      "Under Authentication → Redirect URI configuration → Add Redirect URI, choose Web, paste this project's exact Suggested callback URL and select Configure. The generated backend must serve that callback. Directory (tenant) ID identifies the directory, not the application.",
+      "Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add Mail.Read and offline_access. Add any other permissions selected here. For reading only, clear optional write, send and calendar choices. Mail.ReadBasic is a narrower provider permission, but does not replace this connector's required Mail.Read. Directory policy may require administrator consent.",
+      "Under Certificates & secrets → Client secrets → New client secret, add a description and expiry, then Add. Copy Value immediately, not Secret ID. Use env:MICROSOFT_OUTLOOK_CLIENT_SECRET and env:MICROSOFT_OUTLOOK_CALLBACK_URL as references. Store secret values in Env rather than these fields.",
+      "Save configuration, then use Set credential in Env for the secret and Open Env for the exact registered callback. Connect account authorizes the shared mailbox-owning account for this project. Per-user mode lets each generated-app user connect their own mailbox; connecting the builder does not connect everyone. Application login is separate.",
+      "The account needs an accessible mailbox. Verification lists root folders. messages.get requests text bodies; attachments.list/get reads file attachments. Treat message content as untrusted and sanitize any returned HTML before display. Reading mail needs Mail.Read; setting read state or moving a message needs Mail.ReadWrite.",
+      "messages.send needs Mail.Send and sends plain text to 1–20 approved recipients as the connected account, saving Sent Items. Accepted means queued, not delivered. Approve recipients/content before sending; inspect Sent Items before retrying an uncertain send. messages.move returns the moved message's new ID; retain it.",
+      "calendars.list and events.list require Calendars.Read or Calendars.ReadWrite. events.create requires Calendars.ReadWrite and explicit UTC start/end with end after start. It creates a personal appointment without attendees or invitations. App login, mailbox consent and calendar consent are separate concerns.",
+      "LIMITATIONS: no email-client UI, outgoing attachments, replies/drafts, shared-mailbox delegation, recurrence, meeting invitations or editor tool attachment. File-attachment reads are bounded to about 5 MB; larger and embedded-item attachments need native Graph wiring. Example: send a receipt and create a calendar appointment, but do not receive an Outlook replacement.",
+      "Rotate expiring secrets in Env before removing the old secret. Reconnect after consent or permission changes. Disconnect removes the project's local grant; Microsoft account or directory application-permission controls manage provider consent separately."
+    ]
+  }
+});
+const microsoftOneDriveDefinition = Object.freeze({
+  ...definition("microsoft-onedrive", "Microsoft OneDrive", "Browse folders, obtain file downloads and upload small files.", "Files.Read", "Read your files"),
+  scopes: [
+    { value: "Files.Read", label: "Read your files", required: true, recommended: true },
+    { value: "Files.Read.All", label: "Read all files you can access", recommended: true },
+    { value: "Files.ReadWrite", label: "Read and write your files", recommended: true },
+    { value: "Files.ReadWrite.All", label: "Read and write all files you can access" },
+    { value: "Files.ReadWrite.AppFolder", label: "Read and write files in the application's folder" },
+    { value: "offline_access", label: "Keep access when you are away", recommended: true }
+  ],
+  setup: {
+    url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+    steps: [
+      "In Microsoft Entra admin center → Entra ID → App registrations → New registration, name the application. For common, select accounts in any organizational directory and personal Microsoft accounts. For single tenant, select this directory only and use its Directory (tenant) ID instead. Select Register.",
+      "Copy Application (client) ID from Overview into Client ID. Directory (tenant) ID identifies the directory, not the app. Under Authentication → Redirect URI configuration → Add Redirect URI, choose Web, paste this project's exact Suggested callback URL and select Configure. The generated backend must serve that callback.",
+      "Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add Files.Read and offline_access. Match any additional selected permissions. All permissions cover files the user can access beyond their own files; write permissions allow changes. For listing only, clear the optional read-all and write choices. Directory policy may require administrator consent.",
+      "Under Certificates & secrets → Client secrets → New client secret, add a description and expiry, then Add. Copy Value immediately, not Secret ID. Use env:MICROSOFT_ONEDRIVE_CLIENT_SECRET as the secret reference and env:MICROSOFT_ONEDRIVE_CALLBACK_URL as the callback reference. Secret values belong in Env, not these reference fields.",
+      "Save configuration, then use Set credential in Env for the secret and Open Env for the exact registered callback URL. Connect account authorizes the shared account for this project; each app user connects inside the generated app in per-user mode. This connector does not establish application login.",
+      "Use an account with OneDrive already provisioned. Verification only lists its drive root. Browse folders with items.list(folderId), then items.get for metadata and a short-lived download URL. That URL grants file access: send it only to the authorized app user, never log/cache it, and download without forwarding the Microsoft Authorization header. Folder metadata has no download URL.",
+      "files.upload needs Files.ReadWrite, a parent folder ID, file name and Base64 content up to 5 MB. Its conflict behavior defaults to fail; explicitly approve replace before overwriting. Do not retry uncertain uploads automatically: inspect the folder first.",
+      "LIMITATIONS: larger/resumable transfers use your framework's native Graph upload-session client. No file manager, sharing editor, app-folder automation or Vibe64 tool attachment is supplied. Example: upload a small report and provide its download link; a multi-gigabyte video needs native transfer wiring.",
+      "Replace expiring client secrets in Env before removing the old secret. Reconnect after consent or permission changes. Disconnect removes the project's local grant; remove Microsoft consent separately through the account or directory's application-permission controls."
+    ]
+  }
+});
+const microsoftExcelDefinition = Object.freeze({
+  ...definition("microsoft-excel", "Microsoft Excel", "Browse workbooks and read or update bounded cell ranges with explicit sessions.", "Files.Read", "Read your files"),
+  scopes: [
+    { value: "Files.Read", label: "Read your files", required: true, recommended: true },
+    { value: "Files.ReadWrite", label: "Read and write your files (required by Excel worksheets)", recommended: true },
+    { value: "Files.Read.All", label: "Read all files you can access" },
+    { value: "Files.ReadWrite.All", label: "Read and write all files you can access" },
+    { value: "offline_access", label: "Keep access when you are away", recommended: true }
+  ],
+  setup: {
+    url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+    steps: [
+      "Sign into Microsoft Entra admin center → Entra ID → App registrations → New registration. Name your application. For common, choose accounts in any organizational directory and personal Microsoft accounts; for a single directory, choose single tenant and use its Directory (tenant) ID instead.",
+      "Select Register. Copy Application (client) ID from Overview into Client ID. Under Authentication → Redirect URI configuration → Add Redirect URI, choose Web, paste this project's exact Suggested callback URL and select Configure. The generated application's backend must serve that address.",
+      "Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add Files.Read and offline_access. Add Files.ReadWrite for worksheet access, even when only reading worksheets. The optional All permissions cover broader file access; select them only when needed. Directory policy may require an administrator's consent.",
+      "Under Certificates & secrets → Client secrets → New client secret, choose a description and expiry, then Add. Copy Value immediately, not Secret ID. Use env:MICROSOFT_EXCEL_CLIENT_SECRET as the secret reference and env:MICROSOFT_EXCEL_CALLBACK_URL as the callback reference; never paste the secret into the reference field.",
+      "Save configuration. Use Set credential in Env to store the secret and Open Env to store the same callback URL you registered. For a shared connection, Connect account authorizes the account this project will use; for per-user access, each application user connects inside the generated app. This does not create your application's login session.",
+      "Verification lists the signed-in user's drive root without requiring a workbook ID or changing files. Your app can browse folders using items.list and pass a workbook's returned id to worksheets.list. Worksheet access needs Files.ReadWrite and a supported accessible workbook; successful connection alone does not prove either.",
+      "After selecting a workbook and worksheet, ranges.get reads a bounded A1 address such as A1:B2. ranges.update writes an exactly matching matrix of values OR formulas, up to 10,000 cells. A null cell leaves its existing value unchanged. Your app must approve the target and content before writing; the form itself never edits cells.",
+      "For repeated operations, sessions.create requires an explicit persistChanges choice: true saves edits, false uses a temporary copy. Pass the returned sessionId to each range call and close it with sessions.close. Use a work or school account for sessions; Microsoft does not support personal accounts for session close. Without a session, edits persist. Do not automatically repeat a write after a timeout; inspect the workbook first.",
+      "LIMITATIONS: no workbook creation, charts, pivot tables, formatting editor or asynchronous session polling. Example: update a budget range and formula, but do not receive a spreadsheet designer. Application login and Vibe64 assistant tool attachment remain separate.",
+      "Replace expiring client secrets in Env before deleting the old secret. Reconnect when consent expires or permissions change. Disconnect removes the project's local grant; Microsoft consent remains until removed through the account or directory's application-permission controls."
+    ]
+  }
+});
+const microsoftTeamsDefinition = Object.freeze({
+  ...definition("microsoft-teams", "Microsoft Teams", "Browse teams/channels and read or send channel and existing-chat messages.", "Team.ReadBasic.All", "List joined teams", true),
+  scopes: [
+    { value: "Team.ReadBasic.All", label: "List joined teams", required: true, recommended: true },
+    { value: "Channel.ReadBasic.All", label: "List channels in teams", required: true, recommended: true },
+    { value: "User.Read", label: "Read user profile", required: true, recommended: true },
+    { value: "ChannelMessage.Send", label: "Send messages to channels", recommended: true },
+    { value: "ChannelMessage.Read.All", label: "Read channel messages" },
+    { value: "Chat.ReadWrite", label: "Read and send chat messages" },
+    { value: "User.Read.All", label: "Read all users' full profiles", recommended: true },
+    { value: "offline_access", label: "Keep access when you are away", recommended: true }
+  ],
+  setup: {
+    url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+    steps: [
+      "In Microsoft Entra admin center → Entra ID → App registrations → New registration, name the application and choose accounts in any organizational directory. Select Register and copy Application (client) ID into Client ID. Keep organizations as tenant, or choose single tenant and enter its Directory (tenant) ID. This connector requires a work or school account with Teams access; personal Microsoft accounts are unsupported.",
+      "Under Authentication → Redirect URI configuration → Add Redirect URI, choose Web, paste this project's exact Suggested callback URL and select Configure. The generated backend must serve this callback. Directory (tenant) ID identifies the directory, not the application.",
+      "Open API permissions → Add a permission → Microsoft Graph → Delegated permissions. Add Team.ReadBasic.All, Channel.ReadBasic.All, User.Read and offline_access, plus any optional permissions selected here. For listing teams only, clear optional channel-send and all-user-profile access. The form retains channel/profile read choices; the current teams.list operation uses only Team.ReadBasic.All. Tenant policy and some permissions require administrator consent.",
+      "Open Certificates & secrets → Client secrets → New client secret, enter a description and expiry, then Add. Copy Value immediately, not Secret ID. Keep env:MICROSOFT_TEAMS_CLIENT_SECRET and env:MICROSOFT_TEAMS_CALLBACK_URL as references; store their actual values in Env.",
+      "Save configuration, then use Set credential in Env for the secret and Open Env for the registered callback. Connect account authorizes the shared account for this project. In per-user mode, each generated-app user connects separately. Connecting the builder does not connect everyone; application login is separate.",
+      "Verification lists teams where the signed-in account is a direct member. An empty list can be valid, and access to a shared channel does not necessarily include its host team. Use channels.list for a selected team. Reading messages/replies needs ChannelMessage.Read.All; sending needs ChannelMessage.Send. Enable the chosen permission in Entra and this form, obtain any administrator consent, then reconnect.",
+      "messages.list and replies.list read channel conversations; messages.send and replies.send send plain text to the explicitly selected channel/thread. Existing chats use chats.list, chatMessages.list and chatMessages.send with Chat.ReadWrite. The app must approve each destination and message; do not retry uncertain sends automatically. Sanitize returned HTML before display.",
+      "LIMITATIONS: no team/chat creation, membership changes, message edits/deletion, attachments, meeting bot or Vibe64 tool attachment. Example: read a channel and post an approved status update, but do not receive a Teams client or automatic team administration. Profile-read consent does not create a user-directory feature.",
+      "Rotate expiring secrets in Env before deleting the old secret. Reconnect after consent or permission changes. Disconnect removes local grants; Microsoft account or directory application-permission controls manage provider consent separately."
+    ]
+  }
+});
+const microsoftOneNoteDefinition = Object.freeze({
+  ...definition("microsoft-onenote", "Microsoft OneNote", "Browse notebooks and pages, read content, and create or append text notes.", "Notes.Read", "Read your notebooks"),
+  scopes: [
+    { value: "Notes.Read", label: "Read your notebooks", required: true, recommended: true },
+    { value: "Notes.Read.All", label: "Read notebooks you can access in your organization", recommended: true },
+    { value: "Notes.ReadWrite.All", label: "Read and modify notebooks you can access in your organization", recommended: true },
+    { value: "Notes.Create", label: "Create pages in OneNote notebooks", recommended: true },
+    { value: "Notes.ReadWrite", label: "Read and modify your notebooks", recommended: true },
+    { value: "offline_access", label: "Keep access when you are away", recommended: true }
+  ],
+  setup: {
+    url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+    steps: [
+      "In Microsoft Entra admin center → Entra ID → App registrations → New registration, name your application. For common, choose accounts in any organizational directory and personal Microsoft accounts. For single tenant, choose this directory only and use its Directory (tenant) ID. Select Register and copy Application (client) ID into Client ID.",
+      "Under Authentication → Redirect URI configuration → Add Redirect URI, choose Web, paste this project's exact Suggested callback URL and select Configure. The generated application's backend must serve that address. Directory (tenant) ID is the directory identifier, not the Application (client) ID.",
+      "Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add Notes.Read and offline_access. Match any optional permissions selected here. For listing only, clear all optional notebook permissions. Personal Microsoft accounts must clear both organization-wide All permissions; those require work or school accounts. Tenant policy may require administrator consent.",
+      "Open Certificates & secrets → Client secrets → New client secret, enter a description and expiry, then Add. Copy Value immediately, not Secret ID. Keep env:MICROSOFT_ONENOTE_CLIENT_SECRET and env:MICROSOFT_ONENOTE_CALLBACK_URL as references; put the actual secret and registered callback in Env.",
+      "Save configuration, then use Set credential in Env for the secret and Open Env for the callback. Connect account authorizes the shared account this project will use. In per-user mode, each user connects inside the generated application. OneNote authorization does not create your application's login session.",
+      "Verification lists the signed-in user's notebooks without creating a notebook or changing pages. Browse notebooks, sections and pages with notebooks.list, sections.list and pages.list; pages.content returns HTML up to 1 MiB. The app must sanitize HTML before rendering it, or show it as plain text. Use an account with access to the notebooks your application needs.",
+      "To create a note, add Notes.Create (or Notes.ReadWrite), reconnect, then call pages.create with a section ID, title and plain text. To append text to an existing page, add Notes.ReadWrite and call pages.append with its page ID and text. Text is escaped, not treated as HTML. Approve the destination and content before writes; inspect the page before retrying an uncertain result.",
+      "LIMITATIONS: no rich-text editor, binary attachments, page replacement/deletion, nested section-group traversal or Vibe64 tool attachment. Example: create meeting notes and append an action item, but do not expect an embedded OneNote designer or image upload.",
+      "Rotate expiring client secrets in Env before deleting the old secret. Reconnect after consent or permission changes. Disconnect removes the project's local grant; Microsoft account or directory application-permission controls manage provider consent separately."
+    ]
+  }
+});
+const microsoftSharePointDefinition = Object.freeze({
+  ...definition("microsoft-sharepoint", "Microsoft SharePoint", "Browse sites/libraries, transfer small files and edit list items.", "Sites.Read.All", "Read items in all site collections", true, [
+    { name: "search", required: true, label: "Site search", hint: "Enter a search term for accessible SharePoint sites. Verification performs this search without changing a site." }
+  ]),
+  scopes: [
+    { value: "Sites.Read.All", label: "Read items in all site collections", required: true, recommended: true },
+    { value: "User.Read", label: "Read user profile", required: true, recommended: true },
+    { value: "Sites.ReadWrite.All", label: "Edit or delete items in all site collections", recommended: true },
+    { value: "Sites.Manage.All", label: "Create, edit, and delete items and lists in all site collections" },
+    { value: "Sites.FullControl.All", label: "Have full control of all site collections" },
+    { value: "Files.Read.All", label: "Read all files that user can access", recommended: true },
+    { value: "Files.ReadWrite.All", label: "Read and write all files that user can access" },
+    { value: "offline_access", label: "Keep access when you are away", recommended: true }
+  ],
+  setup: {
+    url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+    steps: [
+      "In Microsoft Entra admin center → Entra ID → App registrations → New registration, name the application and choose accounts in any organizational directory. Select Register and copy Application (client) ID into Client ID. Keep organizations as tenant, or choose single tenant and enter that Directory (tenant) ID. SharePoint site search requires a work or school account; personal Microsoft accounts are unsupported.",
+      "Open Authentication → Redirect URI configuration → Add Redirect URI, choose Web, paste this project's exact Suggested callback URL, then Configure. The generated backend must serve this callback. The tenant ID identifies the directory, not the application.",
+      "Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add Sites.Read.All, User.Read and offline_access, plus any optional permissions selected here. For site search only, clear optional site-write and file permissions. The form retains User.Read for profile access; site search itself requires Sites.Read.All. Tenant policy may require administrator consent. Add Sites.ReadWrite.All for list-item edits or file uploads; reconnect after changing consent.",
+      "Open Certificates & secrets → Client secrets → New client secret, enter a description and expiry, then Add. Copy Value immediately, not Secret ID. Keep env:MICROSOFT_SHAREPOINT_CLIENT_SECRET and env:MICROSOFT_SHAREPOINT_CALLBACK_URL as references; actual values belong in Env.",
+      "Save configuration, then use Set credential in Env for the secret and Open Env for the registered callback. Enter a Site search term before Connect account. This verifies the shared account for this project; per-user mode requires each generated-app user to connect separately. Application login is separate.",
+      "Use an account with access to the intended SharePoint sites. Verification searches site names and other indexed properties without changing a site. Empty results can be a successful search. It does not crawl documents, edit lists or grant access to additional sites. Sites.Selected application permissions are not supported by this search operation.",
+      "After sites.search, use the returned site ID with libraries.list or lists.list. files.list browses a selected drive and folder; files.get supplies metadata/private short-lived download links. Never log these links or forward the Microsoft bearer token to them. files.upload supports up to 5 MB and defaults to fail on an existing name; approve replace explicitly.",
+      "listItems.list returns fields and ETags. listItems.create/update accepts internal column names and scalar values. Updates require the current eTag; if Microsoft returns 412, reload and review the conflicting edit rather than overwriting. Approve the site, list and values in your app before writing.",
+      "LIMITATIONS: no site-collection creation, SharePoint admin UI, complex field editors, sharing/permissions editor or Vibe64 tool attachment. Large/resumable file transfers need native Graph wiring. Example: update a project-status list and upload a report, but do not receive a SharePoint site builder.",
+      "Rotate expiring secrets in Env before removing the old secret. Reconnect after consent or permission changes. Disconnect removes local grants; use Microsoft account or directory application-permission controls to manage provider consent separately."
+    ]
+  }
+});
+const microsoftWordDefinition = Object.freeze({
+  ...definition("microsoft-word", "Microsoft Word", "Browse Word files and folders in your drive and read document metadata.", "Files.Read", "Read your files"),
+  setup: {
+    url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+    steps: [
+      "In Microsoft Entra admin center → Entra ID → App registrations → New registration, name the application. For common, choose accounts in any organizational directory and personal Microsoft accounts. For single tenant, choose this directory only and enter its Directory (tenant) ID. Select Register and copy Application (client) ID into Client ID.",
+      "Under Authentication → Redirect URI configuration → Add Redirect URI, choose Web, paste this project's exact Suggested callback URL and select Configure. The generated backend must serve that callback. Directory (tenant) ID identifies the directory, not the app.",
+      "Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add Files.Read and offline_access. These authorize file reads and ongoing access; the fragment requires no write permission. Directory policy may require administrator consent. Use an account with an existing OneDrive and access to the documents you need.",
+      "Open Certificates & secrets → Client secrets → New client secret, enter a description and expiry, then Add. Copy Value immediately, not Secret ID. Keep env:MICROSOFT_WORD_CLIENT_SECRET and env:MICROSOFT_WORD_CALLBACK_URL as references; actual values go in Env.",
+      "Save configuration, then use Set credential in Env for the secret and Open Env for the exact registered callback. Connect account authorizes the shared account for this project. Per-user mode requires each generated-app user to connect separately; application login is a separate concern.",
+      "Verification lists drive-root folders and document filenames. The app can browse folders and read a selected file's metadata using its returned item ID. It does not read document contents, edit or download documents, execute macros or scan the whole drive. An empty filtered page can still have another page to fetch.",
+      "Rotate expiring secrets in Env before deleting the old secret. Reconnect after consent or permission changes. Disconnect removes local grants; Microsoft account or directory application-permission controls manage provider consent separately."
+    ]
+  }
+});
+const microsoftPowerPointDefinition = Object.freeze({
+  ...definition("microsoft-powerpoint", "Microsoft PowerPoint", "Browse PowerPoint files and folders in your drive and read presentation metadata.", "Files.Read", "Read your files"),
+  setup: {
+    url: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+    steps: [
+      "In Microsoft Entra admin center → Entra ID → App registrations → New registration, name the application. For common, choose accounts in any organizational directory and personal Microsoft accounts. For single tenant, choose this directory only and enter its Directory (tenant) ID. Select Register and copy Application (client) ID into Client ID.",
+      "Under Authentication → Redirect URI configuration → Add Redirect URI, choose Web, paste this project's exact Suggested callback URL and select Configure. The generated backend must serve that callback. Directory (tenant) ID identifies the directory, not the app.",
+      "Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add Files.Read and offline_access. These authorize file reads and ongoing access; the fragment requires no write permission. Directory policy may require administrator consent. Use an account with an existing OneDrive and access to the presentations you need.",
+      "Open Certificates & secrets → Client secrets → New client secret, enter a description and expiry, then Add. Copy Value immediately, not Secret ID. Keep env:MICROSOFT_POWERPOINT_CLIENT_SECRET and env:MICROSOFT_POWERPOINT_CALLBACK_URL as references; actual values go in Env.",
+      "Save configuration, then use Set credential in Env for the secret and Open Env for the exact registered callback. Connect account authorizes the shared account for this project. Per-user mode requires each generated-app user to connect separately; application login is a separate concern.",
+      "Verification lists drive-root folders and presentation filenames. The app can browse folders and read a selected file's metadata using its returned item ID. It does not read slides, edit or download presentations, execute macros or scan the whole drive. An empty filtered page can still have another page to fetch.",
+      "Rotate expiring secrets in Env before deleting the old secret. Reconnect after consent or permission changes. Disconnect removes local grants; Microsoft account or directory application-permission controls manage provider consent separately."
+    ]
+  }
+});
+const microsoftDefinitions = Object.freeze([
+  microsoftOutlookDefinition, microsoftOneDriveDefinition, microsoftExcelDefinition,
+  microsoftTeamsDefinition, microsoftOneNoteDefinition, microsoftSharePointDefinition,
+  microsoftWordDefinition, microsoftPowerPointDefinition
+]);
+export { microsoftOutlookDefinition, microsoftOneDriveDefinition, microsoftExcelDefinition, microsoftTeamsDefinition, microsoftOneNoteDefinition, microsoftSharePointDefinition, microsoftWordDefinition, microsoftPowerPointDefinition, microsoftDefinitions };

package/src/shared/miro.js

@@ -0,0 +1,27 @@
+const miroDefinition = Object.freeze({
+  id: "miro", name: "Miro", description: "Use Miro board tools through the assistant owner's selected team.",
+  accountModes: ["assistant"], authenticationMethods: ["oauth2"],
+  scopes: [
+    { value: "boards:read", label: "Read boards", recommended: true },
+    { value: "boards:write", label: "Create and edit boards" },
+    { value: "openid", label: "Include account identity" },
+    { value: "email", label: "Read your email address" }
+  ],
+  setup: {
+    url: "https://developers.miro.com/docs/connecting-to-miro-mcp",
+    clientRegistrationEndpoint: "https://mcp.miro.com/register",
+    steps: [
+      "This is a Miro MCP assistant connection. Credentials from Miro's REST API Your apps screen cannot be substituted. Keep Assistant access and start with Read boards; select writes or identity access only when the host needs them.",
+      "Enter the exact Suggested callback URL served by your application's backend. Open OAuth client registration below: copy the Registration endpoint and Registration request body into your HTTP client's POST request with Content-Type: application/json. The request includes the current callback and selected permissions. CLI/Node users can instead call registerMiroClient once with those same values.",
+      "Send the registration request once. Copy client_id from the successful response into Client ID. Keep client_secret private and note any reported expiry. A timeout may still have created a client; investigate before retrying. This registers an MCP client and does not connect a Miro account.",
+      "Keep env:MIRO_CLIENT_SECRET and env:MIRO_CALLBACK_URL as references. Save configuration, then use Set credential in Env for the returned secret and Open Env for the exact registered callback. Changing this form does not update an already registered client.",
+      "Click Connect account, sign into Miro and select the team containing the boards you want. Review access and Continue back to your host. Reconnect and choose the correct team if board access fails. Team and organization policies still apply.",
+      "Verification discovers available tools without executing them. The assistant host must authorize each tool and its exact board arguments before use. Discovery does not prove access to a particular board. Identity scopes do not configure app login, and this connection does not attach tools to chat automatically.",
+      "LIMITATIONS: connecting does not attach Miro tools to Vibe64 coding chat. Example: an explicitly wired CLI/assistant host can read a board or request a diagram through discovered tools, but Vibe64 will not automatically see that board in your conversation. This shared attachment feature is deferred. No embedded board editor is provided.",
+      "Reconnect to change teams or consent. Disconnect removes local grants; manage provider access separately in Miro. Keep registration secrets in Env and replace expiring credentials through the provider's supported setup before they expire."
+
+    ]
+  }
+});
+
+export { miroDefinition };

package/src/shared/oura.js

@@ -0,0 +1,23 @@
+const ouraDefinition = Object.freeze({
+  id: "oura", name: "Oura", description: "Connect an individual's Oura account to read sleep, readiness, activity, heart-rate and permitted profile data.",
+  accountModes: ["per-user"], authenticationMethods: ["oauth2"],
+  scopes: [
+    { value: "daily", label: "Read daily sleep, activity and readiness summaries", required: true },
+    { value: "heartrate", label: "Read heart-rate samples" },
+    { value: "personal", label: "Read personal profile information" },
+    { value: "email", label: "Read the account email address" }
+  ],
+  setup: {
+    url: "https://support.ouraring.com/hc/en-us/articles/4415266939155-The-Oura-API",
+    steps: [
+      "Use dailySleep.list, sleep.list, dailyReadiness.list and dailyActivity.list with start_date/end_date, and heartRate.list with start_datetime/end_datetime including timezone. Follow next_token explicitly. LIMITATIONS: no live synchronization, health dashboard, workout/tag/session/SpO2 operations or automatic coding-chat attachment. For example, your app can show a user’s sleep/readiness and heart-rate history; it must build the chart and refresh schedule itself.",
+      "For a new registration, open https://developer.ouraring.com and sign in with the Oura account that will own this application. Create an API application there. To edit an existing registration, Oura still provides My Applications at https://cloud.ouraring.com/oauth/applications. Personal access tokens are retired; use OAuth.",
+      "Provide the application name and website describing your integration. Add the exact Suggested callback URL from this screen to the registration's allowed redirect URIs, including scheme and path. Your application's backend must serve that callback. The hosting URL suggested here is the starting point; update the provider and Env together if your app moves to a custom domain.",
+      "Copy the assigned Client ID here. Keep env:OURA_CLIENT_SECRET and env:OURA_CALLBACK_URL as references and Save configuration. Use Set credential in Env to store the Client Secret as OURA_CLIENT_SECRET, and Set callback in Env to store the registered URL as OURA_CALLBACK_URL. Keep the actual secret out of configuration JSON and chat.",
+      "Keep daily permission selected: verification reads daily sleep summaries. Select heartrate only for heart-rate samples; personal or email only if your application needs those profile fields. Each app user connects their own account and may decline individual permissions; declining daily prevents this connection from being verified. This grants Oura data access, not application login.",
+      "In Vibe64, choose Prepare app user connection request to prepare the application wiring. Once implemented, each user opens the application's own account screen, connects Oura and approves access. Oura documents a ten-user limit before application approval; request review from the application's page for wider use. Gen3 and later users need an active Oura Membership for API data. If verification is forbidden, check membership and granted permissions; an empty sleep list can mean there is no synced data yet.",
+      "In the application, reconnect starts consent again and disconnect removes that user's local grant; manage the application's authorization in Oura separately. The application owns stored grants and single-use refresh tokens, including after leaving Vibe64. Preserve its private connection store when moving hosts."
+    ]
+  }
+});
+export { ouraDefinition };

package/src/shared/posthog.js

@@ -0,0 +1,33 @@
+import { createSchema } from "json-rest-schema";
+
+const posthogDefinition = Object.freeze({
+  id: "posthog", name: "PostHog", description: "Capture events and evaluate flags with a public project token.",
+  accountModes: ["shared", "assistant"], authenticationMethods: ["api-key"], scopes: [],
+  apiKeyReferenceLabel: "Project token reference",
+  verificationFields: [{ name: "distinct_id", required: true, label: "Verification user ID",
+    hint: "Enter the identity whose feature flags should be evaluated. This check does not submit an analytics event." }],
+  apiKeyReferenceHint: "Use an environment reference for the project's public token (phc_). Your app may expose that token in its frontend. It cannot read private analytics.",
+  settingsSchema: createSchema({
+    region: { type: "string", enum: ["eu", "us"], defaultTo: "eu" },
+    projectId: { type: "string", required: true, minLength: 1, maxLength: 20,
+      validator: (value) => /^[1-9][0-9]*$/u.test(value) || "Enter the numeric project ID from PostHog project settings." }
+  }),
+  settingsFields: [
+    { name: "region", label: "Region", hint: "Choose the PostHog Cloud region containing this project.", items: [
+      { value: "eu", title: "Europe (eu.i.posthog.com)" }, { value: "us", title: "United States (us.i.posthog.com)" }
+    ] },
+    { name: "projectId", label: "Project ID", placeholder: "12345",
+      hint: "Public numeric ID from project settings. Public API requests use the token to select the project; verification does not match this ID to the token." }
+  ],
+  setup: {
+    url: "https://posthog.com/docs/settings/projects",
+    steps: [
+      "Sign into the intended PostHog Cloud region. Use the project switcher to create or select the project's analytics destination.",
+      "Open Project settings and copy its numeric project ID and public project token (phc_). Keep that project's region selected here.",
+      "Store the project token in Env and enter its reference. This is a publishable token, not a personal, project-secret or OAuth API key.",
+      "Save the configuration. The application runtime verifies token acceptance by evaluating flags for an explicitly supplied user identifier.",
+      "Event capture is a separate operation. Verification does not submit an analytics event or prove final event ingestion."
+    ]
+  }
+});
+export { posthogDefinition };

package/src/shared/prestashop.js

@@ -0,0 +1,23 @@
+import { createSchema } from "json-rest-schema";
+import { httpsSiteUrlField } from "./siteUrl.js";
+
+const prestashopDefinition = Object.freeze({
+  id: "prestashop", name: "PrestaShop", description: "Read products and orders from your PrestaShop store.",
+  accountModes: ["shared", "assistant"], authenticationMethods: ["api-key"], scopes: [],
+  apiKeyReferenceLabel: "Webservice API key reference",
+  apiKeyReferenceHint: "Store the Webservice key outside source. Grant GET for products, and for orders if the application needs order reads.",
+  settingsSchema: createSchema({ siteUrl: httpsSiteUrlField }),
+  settingsFields: [{ name: "siteUrl", label: "Store URL", placeholder: "https://shop.example.com",
+    hint: "Use the HTTPS store address before /api, keeping any installation subdirectory." }],
+  setup: {
+    url: "https://devdocs.prestashop-project.org/9/webservice/tutorials/creating-access/",
+    steps: [
+      "Open Advanced Parameters, Webservice in your store's back office. Enable PrestaShop Webservice and save.",
+      "Choose Add new webservice key, Generate, enter a description and enable the key. Grant GET for products and any required orders access.",
+      "In multistore mode select the intended shop association, then save. Store the key in Env and enter its reference here.",
+      "Use the final HTTPS store URL. The runtime verifies a product read; it does not verify order permissions or modify store data."
+    ]
+  }
+});
+
+export { prestashopDefinition };

package/src/shared/salesforce.js

@@ -0,0 +1,36 @@
+import { createSchema } from "json-rest-schema";
+
+const label = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+const production = new RegExp(`^https://${label}(?:\\.develop)?\\.my\\.salesforce\\.com/?$`, "u");
+const sandbox = new RegExp(`^https://${label}\\.sandbox\\.my\\.salesforce\\.com/?$`, "u");
+const salesforceDefinition = Object.freeze({
+  id: "salesforce", name: "Salesforce", description: "Explore Salesforce objects and read records with your organisation's API permissions.",
+  accountModes: ["shared", "per-user", "assistant"], authenticationMethods: ["oauth2"],
+  oauthClientAuthenticationMethods: ["client_secret_post"],
+  settingsSchema: createSchema({
+    environment: { type: "string", enum: ["production", "sandbox"], defaultTo: "production" },
+    accountUrl: { type: "string", required: true, noTrim: true, maxLength: 253, validator: (value, object) =>
+      (object.environment === "sandbox" ? sandbox : production).test(value) || "Enter a lowercase HTTPS My Domain URL matching the selected environment, without a path, query or port." }
+  }),
+  settingsFields: [
+    { name: "environment", label: "Environment", items: [{ value: "production", title: "Production" }, { value: "sandbox", title: "Sandbox" }],
+      hint: "Production includes Developer Edition. Sandbox uses the org's .sandbox.my.salesforce.com domain." },
+    { name: "accountUrl", label: "Account URL", placeholder: "https://acme.my.salesforce.com",
+      hint: "Copy My Domain from Salesforce Setup. The same org receives authorization and API requests." }
+  ],
+  scopes: [
+    { value: "api", label: "Access Salesforce APIs with this user's permissions", recommended: true },
+    { value: "refresh_token", label: "Keep access when the user is away", recommended: true }
+  ],
+  permissionsHint: "Salesforce's api permission can allow writes. This runtime exposes reads; your app still authorizes each query. Connecting an account does not sign the person into your application.",
+  setup: { url: "https://help.salesforce.com/s/articleView?id=sf.external_client_apps.htm&type=5", steps: [
+    "In Salesforce Setup, open My Domain and copy the org's login URL. Select Production for production/Developer Edition or Sandbox for a sandbox org.",
+    "Open External Client App Manager and create an External Client App. Enter its name, API name and contact email; use Local for an app used only by this org.",
+    "Enable OAuth, register the exact backend callback, and select api plus refresh_token/offline_access. Keep PKCE enabled and require the secret for Web Server and Refresh Token flows.",
+    "Open the app's Settings, then Consumer Key and Secret. Copy the key as Client ID; put the secret and callback in Env and save their references here.",
+    "An administrator grants API access and authorizes the app/users through its policies and permission sets. Save configuration, then start consent from your application's connection flow.",
+    "Public/Online registrations need separate provisioning and distribution decisions. Local apps cannot serve unrelated customer orgs; packaged apps require installation and subscriber policies. Org API quotas remain shared."
+  ] }
+});
+
+export { salesforceDefinition };

package/src/shared/semrush.js

@@ -0,0 +1,24 @@
+import { createSchema } from "json-rest-schema";
+import { secretReference } from "@jskit-ai/connectors-core/shared/configuration";
+
+const semrushDefinition = Object.freeze({
+  id: "semrush", name: "Semrush", description: "Read keyword and backlink reports and manage Semrush projects using a V4 API key.",
+  accountModes: ["shared", "assistant"], authenticationMethods: ["api-key"], scopes: [],
+  settingsSchema: createSchema({ v3ApiKeyRef: { ...secretReference, required: false } }),
+  settingsFields: [{ name: "v3ApiKeyRef", label: "V3 API key reference (optional)", placeholder: "env:SEMRUSH_V3_KEY",
+    environmentCredential: { label: "Semrush V3 API key", public: false },
+    hint: "For domain overview and domain/URL/subfolder keyword reports and position tracking: My profile > API Keys > copy your Version 3 key into this project's Env. Leave empty if only using V4 reports/projects." }],
+  apiKeyReferenceLabel: "V4 API key reference",
+  apiKeyReferenceHint: "Use a new Semrush V4 key: Read-only for reports and project reads, Read and write for creating, renaming or deleting projects. V3 keys and OAuth tokens are different credentials.",
+  setup: { url: "https://developer.semrush.com/api/v4/get-started/quick-start/", steps: [
+    "Open the profile icon in Semrush, then My profile > API Keys > + Create API key.",
+    "Create a V4 key for this application. Select Read-only for reports and project reads, or Read and write if the app creates, renames or deletes projects; choose an expiry. Projects access requires SEO Business and available API units.",
+    "Copy the key into Env when it is shown and save only its reference here. This flow needs no Client ID, secret or callback URL.",
+    "The runtime verifies project access. OWN is the default list scope; ALL, SHARED and CORPORATE are explicit operation inputs.",
+    "Keyword metrics and backlink overview, links, referring domains and anchors use this V4 key. These Early Access reports consume account API units only when the app requests them; connecting verifies projects, not every report entitlement.",
+    "Project deletion permanently removes the project, tools, settings and history. The generated app must confirm and authorize this action. Disconnecting here only removes local connection state.",
+    "For domain overview and organic/paid keyword reports for domains, URLs and subfolders, open My profile > API Keys and copy the autogenerated Version 3 key into Env using the optional V3 reference. It is sent only to Semrush for V3 reports. Do not paste it into the V4 field. Position tracking uses this V3 key too: discover campaigns from the project ID, then use the returned campaign ID for dates and ranking reports. Existing campaigns and harvested data are required. OAuth remains unimplemented.",
+    "Separate keys on one account share account capacity. This initial runtime does not implement the captured OAuth connection or individual app-user login."
+  ] }
+});
+export { semrushDefinition };

package/src/shared/shopify.js

@@ -0,0 +1,51 @@
+import { createSchema } from "json-rest-schema";
+
+const shopifyDefinition = Object.freeze({
+  id: "shopify", name: "Shopify", description: "Connect a Shopify store and control what the assistant may change.",
+  accountModes: ["shared", "assistant"], authenticationMethods: ["oauth2", "api-key"],
+  oauthGrantTypes: ["client_credentials"], oauthClientAuthenticationMethods: ["client_secret_post"],
+  authenticationLabels: { oauth2: "App in your Shopify organization", "api-key": "Existing Admin API access token" },
+  authenticationHint: "Client credentials require the app and store in the same Shopify organization. Connecting another merchant requires a separate Shopify installation flow.",
+  apiKeyReferenceLabel: "Admin API access token reference",
+  apiKeyReferenceHint: "Use env:SHOPIFY_ADMIN_TOKEN. A Storefront token, client secret or App Automation Token cannot be used here.",
+  settingsSchema: createSchema({
+    shopDomain: { type: "string", required: true, noTrim: true, maxLength: 77,
+      validator: (value) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.myshopify\.com$/u.test(value) ||
+        "Enter the store's permanent name.myshopify.com domain without a protocol, path or port." }
+  }),
+  settingsFields: [{ name: "shopDomain", label: "Shopify store domain", placeholder: "your-store.myshopify.com",
+    hint: "Use the permanent myshopify.com address, including when your storefront uses a custom domain." }],
+  scopes: [
+    { value: "read_products", label: "Read products", recommended: true },
+    { value: "write_products", label: "Create, update and delete products" }
+  ],
+  permissionsHint: "Match the scopes approved for the installed Shopify app. Write access includes reads. Assistant permission choices do not grant Shopify scopes or staff permissions.",
+  assistantActions: [
+    { value: "enable", label: "Enable Shopify" },
+    { value: "connect", label: "Connect your Shopify store" },
+    { value: "claim", label: "Claim your store" },
+    { value: "products.list", label: "Read products" },
+    { value: "products.create", label: "Create product" },
+    { value: "products.update", label: "Update product" },
+    { value: "products.delete", label: "Delete product" },
+    { value: "variants.create", label: "Add product variant" },
+    { value: "variants.update", label: "Update product variant" },
+    { value: "variants.delete", label: "Delete product variant" },
+    { value: "discountCodes.create", label: "Create discount code" },
+    { value: "discountCodes.update", label: "Update discount code" },
+    { value: "discountCodes.delete", label: "Delete discount code" },
+    { value: "priceRules.create", label: "Create price rule" },
+    { value: "priceRules.update", label: "Update price rule" },
+    { value: "priceRules.delete", label: "Delete price rule" }
+  ],
+  setup: { url: "https://shopify.dev/docs/apps/build/authentication-authorization/client-credentials-grant", steps: [
+    "Open the Shopify Dev Dashboard, choose your organization, open Apps and create an app for your store.",
+    "Create and release an app version with read_products; add write_products only for product changes. Install the app on the store.",
+    "Open the app's Settings and copy its Client ID. Put the Client Secret in Env and enter its reference here.",
+    "Use the store's permanent myshopify.com domain. The client-credentials mode requires both app and store to belong to the same Shopify organization.",
+    "An existing Admin API token can be supplied through Env instead. It grants access as the installed app, not as each shopper or staff member.",
+    "Assistant permissions govern requests made through an assistant runtime. Store creation, claiming, additional merchant consent, variants and discounts require the remaining Shopify flows."
+  ] }
+});
+
+export { shopifyDefinition };

package/src/shared/siteUrl.js

@@ -0,0 +1,12 @@
+function validSiteUrl(value) {
+  if (!/^https:\/\//iu.test(value) || /[\s\\?#]/u.test(value) || /\/(?:\.|%2e){1,2}(?:\/|$)/iu.test(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && Boolean(url.hostname) && !url.username && !url.password && !url.search && !url.hash;
+  } catch { return false; }
+}
+
+const httpsSiteUrlField = { type: "string", required: true, minLength: 1, maxLength: 2048,
+  validator: (value) => validSiteUrl(value) || "Use an HTTPS site URL without credentials, a query, fragment or parent-path segments." };
+
+export { httpsSiteUrlField };