@jskit-ai/connectors-catalog 0.1.1

package/docs/sentry.md

@@ -0,0 +1,112 @@
+# Sentry
+
+Import `sentryProvider` and `registerSentryClient` from
+`@jskit-ai/connectors-catalog/server/sentry`.
+
+The connector uses Sentry's hosted MCP service for an explicitly composed
+assistant. It does not configure SDK event ingestion, a DSN or application login.
+Vibe64 coding-assistant attachment remains deferred. Saving this configuration
+alone does not give editor chat access to Sentry.
+
+## Configure access
+
+1. Open the intended organization in Sentry. Copy its slug from the URL, then
+   open Project Settings and copy the project slug if restricting to one project.
+   Use slugs, not display names or numeric IDs. Organization selection is required;
+   project selection is recommended.
+2. Make the assistant host serve its own HTTPS OAuth callback. In Vibe64, enter
+   it in **Suggested callback URL**, then choose **Register client and connect**.
+   From a trusted backend or CLI instead, call `registerSentryClient` with `clientName`, `callbackUrl`
+   and `scopes` (start with `org:read`). It registers at
+   `https://mcp.sentry.dev/oauth/register`. Registration is an explicit action;
+   inspect an uncertain result before retrying.
+3. Store the returned client ID in the portable registration and the secret in
+   private Env. Set the exact callback in Env too. Select OAuth and assistant
+   ownership, with `settings.organizationSlug` and optional `settings.projectSlug`.
+   This is registration with the MCP service, not a Sentry REST OAuth application.
+4. Connect through the application's OAuth flow and review Sentry's consent.
+   The configuration offers organization read and project/team/event write scopes.
+   Sentry's granted MCP skills and account permissions also determine the tools
+   available. A configured scope does not independently grant access.
+5. Reconnect when access expires or the selected resource changes. Local
+   disconnect removes the saved grant; provider-side permissions remain separate.
+
+The same portable configuration is usable without the editor:
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "sentry-client": {
+      "source": "own",
+      "clientId": "REPLACE_WITH_REGISTERED_CLIENT_ID",
+      "clientSecretRef": "env:SENTRY_CLIENT_SECRET",
+      "callbackUrlRef": "env:SENTRY_CALLBACK_URL"
+    }
+  },
+  "integrations": {
+    "debugging": {
+      "provider": "sentry",
+      "accountMode": "assistant",
+      "scopes": ["org:read"],
+      "authentication": { "method": "oauth2", "registrationRef": "sentry-client" },
+      "settings": { "organizationSlug": "your-org", "projectSlug": "your-project" }
+    }
+  }
+}
+```
+
+Supply the actual client secret and callback through the application's Env.
+Compose `createConnectionService` with this configuration, `sentryProvider`,
+the application's encrypted store, reference resolver and authorization callback.
+Use `beginAuthorization` and `completeAuthorization` for the browser round trip;
+invoke `tools.list`/`tools.call` only under the owning application's authenticated
+context. The CLI/operator also needs a backend capable of receiving the callback.
+
+## Runtime and ownership
+
+`tools.list` discovers available tool schemas, with an explicit optional cursor.
+`tools.call` takes `name` and `arguments`; the host must authorize that exact
+request before provider traffic. Do not hardcode tool availability from examples.
+The selected resource is
+`https://mcp.sentry.dev/mcp/{organizationSlug}[/{projectSlug}]` for both OAuth and
+MCP requests. The provider constrains that resource; the application still owns
+caller authorization and review of any triage or write operation.
+
+The application owns tokens, encrypted persistence, callback execution and
+refresh. CLI applications use the ordinary connection service without Vibe64.
+Other frameworks consume the same configuration and Env names using their native
+OAuth/MCP libraries, without importing JavaScript or running a Node sidecar.
+The editor's subscription does not supply a Sentry account or quota.
+
+## Pre-release configuration change
+
+The previous Sentry REST fragment used `api-key` and `organizations.list`.
+Replace that declaration with the MCP OAuth registration and assistant mode
+above, set the intended organization/project, and connect again. A personal
+Sentry token is not the MCP OAuth client secret. Replace REST operation calls
+with explicit MCP discovery and authorized tool calls. No alias or automatic
+conversion retains the old connection; remove its local record through its
+owning application and review whether its old Env token is still used elsewhere.
+
+## Verification and limitations
+
+Two focused tests cover resource and registration validation. Seven OAuth/MCP
+tests cover consent, PKCE, encrypted persistence, refresh, owner/resource
+isolation, issue details, exact tool authorization, errors and cancellation;
+those seven also pass through installed public package exports. Public editor
+registration has a passing owner/Env test, and phone/desktop browser checks cover
+registration, consent cancellation, reconnect, reload and disconnect. All use
+controlled fixtures; live tool schemas, consent and account behavior are unverified.
+The previous REST organization probe is replaced without a compatibility alias.
+
+The official repository also documents a remote `Sentry-Bearer` token alternative,
+distinct from OAuth `Bearer`. That alternative is not implemented here yet.
+
+Sources: [hosted MCP instructions](https://mcp.sentry.dev/),
+[official implementation](https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-cloudflare/src/server/index.ts),
+[resource binding](https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-cloudflare/src/server/protected-resource-metadata.ts),
+[OAuth metadata](https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-cloudflare/src/server/authorization-server-metadata.ts),
+[scope definitions](https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-core/src/scopes.ts).
+Public discovery requests returned HTTP 403 from the development environment;
+source evidence does not establish successful live consent.

package/docs/sevdesk.md

@@ -0,0 +1,107 @@
+# Sevdesk
+
+Import `sevdeskProvider` from `@jskit-ai/connectors-catalog/server/sevdesk`.
+This fragment verifies an account API token and lists contacts, including people
+by default. Vibe64 labels its credential field **API token reference**.
+
+## Provider setup
+
+1. Sign into the intended sevdesk account with permission to view its API token.
+   Open **Erweiterungen → Integrationen**.
+2. Find **API-Token für Integrationen** near the top. Choose **Einblenden**,
+   enter your password, then copy the revealed token. Some plans also expose
+   **Erweiterungen → API**, with the same reveal/password step.
+3. Store the value as `SEVDESK_API_TOKEN` in the backend environment. Add
+   Sevdesk in Vibe64 and enter `env:SEVDESK_API_TOKEN` in **API token reference**.
+   The portable file contains that reference, never the revealed token.
+
+This retrieves an existing credential; it is not a new OAuth-app registration.
+[Provider token instructions](https://hilfe.sevdesk.de/de/articles/9374740-wo-finde-ich-meinen-api-token-in-sevdesk).
+
+## Configuration and library calls
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "contacts": {
+      "provider": "sevdesk",
+      "displayName": "Business contacts",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "api-key", "secretRef": "env:SEVDESK_API_TOKEN" }
+    }
+  }
+}
+```
+
+The shared authentication method is named `api-key`; this provider's UI and
+documentation call its value a token. Compose `providers: [sevdeskProvider]`
+using the [API-key pattern](../patterns/api-key-connection/PATTERN.md), an
+application authorization policy and the file connection store. CLI and editor
+use the same configuration. Runtime connection records remain text files
+outside exported source, with no database requirement.
+
+```js
+await connections.connectApiKey({ context, integrationId: "contacts" });
+const page = await connections.invoke({
+  context, integrationId: "contacts", operation: "contacts.list",
+  input: { limit: 100, offset: 0, countAll: true }
+});
+```
+
+The provider requires the token directly in `Authorization`, without a Bearer
+prefix. Requests use `GET https://my.sevdesk.de/api/v1/Contact`.
+`limit` accepts 1–1000; `offset` skips records; `countAll: true` asks for a
+`total`, which the provider can return as a numeric string. The collection is
+in `objects`. With `depth: 1`, contacts include organizations and people;
+the provider's normal depth-zero listing includes organizations only.
+Its API documentation identifies credentials with administrator users.
+[API documentation](https://api.sevdesk.de/).
+
+This fragment defaults to `limit: 100`, `offset: 0`, `countAll: false` and
+`depth: 1`. An application can explicitly choose `depth: 0`. Integer pagination
+is required and the local offset cap is 1000000. Results preserve provider
+fields, accept empty collections and validate `total` when present. Request
+subsequent offsets explicitly; no background crawl occurs. Text searches,
+embedded related objects and writes are not implemented.
+
+Requests stay on the fixed HTTPS origin and reject redirects. A changed token
+is resolved on the next call; invalid credentials require verification again.
+Disconnect removes local state and does not revoke the provider token or delete
+its owning user. Account/user lifecycle changes belong in the provider console.
+The application must authorize access to this shared directory; reading a
+contact does not sign that person into the application.
+
+## Automation and application ownership
+
+An AI can write the config, environment reference, library composition and
+contact-list code. The reviewed documents describe a password-confirmed token
+reveal, not a public API for provisioning accounts or generating these tokens.
+Keep that initial step with the account owner; do not fabricate a creation or
+rotation endpoint.
+
+The application owns its token and private Env reference. Two
+references to one token still access one account. Do not promise separate
+provider credentials or quota merely by changing those names, and do not create
+provider users solely as an assumed quota workaround. Customer-owned
+connections use each customer's authorized token. Provider limits and any
+independent-capacity arrangement need confirmation. The application enforces
+its own usage limits. No callback URL is
+used, so editor VM and app hosting domains do not affect this flow.
+
+## Focused evidence
+
+Tests use simulated HTTP replies and real temporary encrypted JSON storage.
+They cover raw authorization, page defaults, explicit organization-only reads,
+numeric-string totals, invalid inputs/envelopes, restart, rotation, ownership
+and disconnect. Editor automation verifies the token label, reference-only
+storage and save/reload. Live provider use, account creation and sample-app
+generation are excluded.
+
+## Existing-scope closeout — 13 September 2026
+
+Contact listing only, including people by default (`depth: 1`), explicit organization-only depth, bounded offset pagination and numeric-string totals. The project supplies its existing raw API token through Env. No contact detail/search/create/update/delete, related-object expansion, invoices, orders, vouchers or bookkeeping operations are implemented. There is no OAuth/app registration, application-user login, token-issuance automation, automatic pagination/retry or remote token revocation. Applications still own their UI, authorization and pagination; disconnect removes local connection state. Deferred work is the missing contact/accounting operations and their validation, permissions, setup guidance and tests. No live Sevdesk account, provider-console login or generated-app run was tested.
+
+Three selected source tests and the same three installed-package tests passed on September 13. They cover credential verification, encrypted file restart, rotation, isolation, disconnect, pagination/depth/totals and redacted invalid-input/provider failures. Existing shared business-token UI evidence is retained; no fresh browser run or form change is claimed.

package/docs/shopify.md

@@ -0,0 +1,206 @@
+# Shopify
+
+The initial runtime connects an existing store, lists products, and creates,
+updates or deletes one product per call. It uses GraphQL Admin API **2026-07**.
+It does not generate a storefront or activate a store. The portable assistant
+policy includes the captured lifecycle, variant, discount and price-rule choices;
+those choices do not claim that the corresponding provider operation exists yet.
+
+## Configuration and ownership
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "shopify-own": {
+      "source": "own",
+      "grantType": "client_credentials",
+      "clientId": "your-shopify-client-id",
+      "clientSecretRef": "env:SHOPIFY_CLIENT_SECRET"
+    }
+  },
+  "integrations": {
+    "shopify": {
+      "provider": "shopify",
+      "displayName": "Company store",
+      "accountMode": "shared",
+      "authentication": { "method": "oauth2", "registrationRef": "shopify-own" },
+      "settings": { "shopDomain": "your-store.myshopify.com" },
+      "scopes": ["read_products", "write_products"],
+      "assistantPolicy": {
+        "enabled": true,
+        "defaultPermission": "ask",
+        "actions": { "products.list": "always", "products.delete": "never" }
+      }
+    }
+  }
+}
+```
+
+Keep the secret value in the application's environment, with the same reference
+used by CLI and editor. For an existing Admin API access token, replace
+`authentication` with `{ "method": "api-key", "secretRef": "env:SHOPIFY_ADMIN_TOKEN" }`
+and remove the unused registration. Storefront tokens, App Automation Tokens,
+client secrets and Customer Account tokens are different credentials.
+
+The store is a shared account. Authorize each application user before mapping to
+its stable shared subject. Neither token mode authenticates shoppers or enforces
+each staff member's individual Shopify role. A per-staff installation needs
+Shopify online access tokens and its separate consent flow, still unfinished here.
+An assistant must use a service composed with `executionMode: "assistant"`;
+`accountMode` describes whose connection is used, not who invoked the operation.
+
+## Manual setup: app and store in the same organization
+
+1. Sign into the [Dev Dashboard](https://dev.shopify.com/) with permission to
+   create apps and install them on the target store. Select the organization that
+   owns the store. Both app and store must appear in this organization.
+2. Open **Apps → Create app**. Choose the Dev Dashboard creation option, enter
+   your application name and create it. An existing app can be selected instead.
+3. Open **Versions → Create a version**. Set the application URL to your actual
+   app entry point. Configure the app's access scopes: `read_products` for the
+   reader, `write_products` when product changes are required. Release the version.
+   A write scope includes reads; the runtime accepts either for product listing.
+4. Install the released app on the intended store and approve its scopes. Update
+   the installation when changing scopes; editing local JSON alone grants nothing.
+5. Open the app's **Settings → Credentials**. Copy **Client ID** into the portable
+   registration. Put **Client secret** in Env and set its reference in the form.
+6. Find the store's permanent `*.myshopify.com` address and enter it without
+   `https://`, paths, ports or a custom storefront domain.
+7. Select **App in your Shopify organization** in the editor. Save configuration.
+   The backend or trusted CLI calls `connectClientCredentials` to acquire a token
+   and verify a product read before reporting Connected.
+8. Keep the shared subject and application/environment identity stable. The
+   runtime persists encrypted connection state and obtains another grant before
+   the documented 24-hour token expires. No callback URL is used in this mode.
+
+If Shopify reports `shop_not_permitted`, correct ownership/distribution. Installing
+an app on another merchant's store does not make client credentials applicable.
+See [organization authentication](https://shopify.dev/docs/apps/build/authentication-authorization/client-credentials-grant)
+and [credential locations](https://shopify.dev/docs/apps/build/authentication-authorization/manage-credentials).
+
+## Manual setup: existing Admin API token
+
+For a legacy custom app created in Shopify admin before January 2026, open the
+store's **Settings → Apps and sales channels → Develop apps**, select the app,
+review its Admin API scopes and installation, and use its existing Admin API token.
+If the secret cannot be revealed again, follow Shopify's credential recovery or
+replacement procedure; do not assume the editor can retrieve it. New apps use the
+Dev Dashboard flow instead. See [legacy custom apps](https://shopify.dev/docs/apps/build/authentication-authorization/legacy/admin-custom-apps).
+
+Choose **Existing Admin API access token**, enter the secret's Env reference and
+the permanent store domain, and save. The app/CLI calls `connectApiKey`; it performs
+a product read before persisting Connected. Token rotation is read from the same
+reference on subsequent requests. The scopes in configuration limit permitted
+operations locally; Shopify remains the authority for the token's actual rights.
+
+## Application registrations, callbacks and domains
+
+Shopify's word *online* describes a staff-user access token. It is unrelated to
+the Vibe64 Online product.
+
+The application owner creates its Shopify app in the Dev Dashboard, configures
+its distribution, access scopes and application URL, and completes any required
+review. Follow the app/version/release steps above and store its client secret
+in the application's private Env. Public distribution, custom distribution and
+organization-only apps are not interchangeable.
+
+The supported client-credentials flow does not require a callback. Merchant
+consent is a separate unfinished flow: it needs the application's actual allowed
+redirect URI, signed Shopify callback validation and the appropriate installation
+lifecycle. Online staff sessions are also unfinished in this adapter. Follow
+Shopify's [authentication guide](https://shopify.dev/docs/apps/build/authentication-authorization)
+and official libraries; do not substitute a generic OAuth callback without
+Shopify's required verification.
+
+For that consent flow, changing the callback domain requires updating the app's
+registration and Env. Retain the application's identity and persistent state
+when moving hosts. A token remains bound to its shop and registration; changing
+provider registrations requires a new installation/grant.
+
+GraphQL Admin quotas are scoped to an **app/store pair**. Separate registrations
+do not remove store resource limits, Shopify plans or review requirements.
+[API limits](https://shopify.dev/docs/api/usage/limits).
+
+## Store creation and claiming
+
+For an ordinary partner handover: Dev Dashboard **Stores → Create store → Client
+transfer store**, enter the name and country/region, then create it. To hand over,
+open the **Client transfer** tab, use the store's **⋯ → Transfer store**, enter the
+client email and submit. The client accepts ownership and selects a plan in
+Shopify. Only perform those external actions with the owner's authorization.
+
+This is a distinct host lifecycle, not a GraphQL product mutation. Shopify places
+installation restrictions on client transfer stores; dev stores cannot be
+transferred. A transfer also moves the store out of the original organization,
+so organization-only client credentials cannot be assumed to remain usable.
+Vibe64's automatic create/claim workflow and any commercial Shopify arrangement
+are not delivered by this fragment. Do not promise Lovable's trial terms.
+See [client transfer stores](https://shopify.dev/docs/apps/build/stores/client-transfer-stores).
+
+## Runtime and assistant authorization
+
+Import `shopifyProvider` from `@jskit-ai/connectors-catalog/server/shopify` and
+compose it with `createConnectionService`, the shared file store and a trusted
+reference resolver. Supported provider operations:
+
+| Operation | Input | Result |
+|---|---|---|
+| `products.list` | `first` 1–100 (20 default), optional opaque `after`, Shopify search `query` | GraphQL envelope with product nodes and page cursor |
+| `products.create` | `product.title`; optional descriptionHtml, vendor, productType, status, tags | Confirmed product and empty userErrors; defaults to DRAFT |
+| `products.update` | `product.id` (Product GID) plus one or more supported product fields | Confirmed updated product |
+| `products.delete` | `input.id` (Product GID) | Confirmed deletedProductId; synchronous request |
+
+No raw GraphQL or caller-supplied destination is accepted. Product IDs are GraphQL
+GIDs, not numbers. Product status does not publish it to sales channels. Price and
+SKU changes belong to variants and are not accepted by these product mutations.
+Mutations are not automatically retried. A timeout may leave a completed Shopify
+change: inspect the store before retrying, particularly after creation.
+
+For assistant execution, compose the same service with `executionMode: "assistant"`.
+The existing `authorize(context, request)` callback still verifies application
+access and returns the trusted `applicationId` and `subjectId`. When
+`request.assistantPermission.decision === "ask"`, it must also verify the human's
+approval for that exact action/input and return `approved: true`. No such result
+means `connector_approval_required`; `never` or disabled access stops before any
+credential lookup or provider request. `always` still requires application access.
+The host owns its approval UI, decision persistence, expiry and single-use checks.
+Never copy `approved`, execution mode or owner identity from a browser request.
+
+`authorizeAssistantAction({ context, integrationId, action: "claim", input })`
+allows a host to apply the same policy before its own lifecycle operation. It
+performs authorization only, never store creation, claiming or API calls. Use
+`invoke` for the implemented product operations. The lifecycle host must still
+validate its input and satisfy workspace policy. There is no new approval database.
+
+The shared form offers access enablement, **Manage all permissions** and all
+captured action choices. Changing the default resets individual overrides; choices
+are `ask`, `always`, `never`. The policy lives outside credential settings, so a
+policy edit does not invalidate a store grant. Workspace-level availability and
+the actual editor assistant tool wiring remain separate unfinished host work.
+
+## Automation feasibility and verification
+
+AI can author/validate the portable file, wire the shared runtime and file store,
+prepare Shopify app configuration, and perform supported product operations
+through the application's authorized server. CLI/deployment automation can update
+an existing app after an operator establishes its organization and credentials.
+An App Automation Token authenticates Shopify CLI automation; it is not the
+Admin API token used by this runtime.
+
+Account/organization creation, merchant consent, review, billing, store transfer
+and any partner agreement require the appropriate human/provider process. A public
+API for silently provisioning both platform apps or reproducing Lovable's special
+create/claim arrangement has not been established. Do not invent one.
+
+Local fixture tests cover organization grants and renewal, existing tokens,
+encryption/restart, product operations and bounds, scopes, ownership and store
+isolation, assistant decisions, error responses and cancellation. They make no
+live Shopify calls. A credentialed store is still required to prove installation,
+actual product access, provider quotas and account-specific permissions. The full
+merchant-consent, managed, variant/discount and store lifecycle flows remain open.
+
+Operation references: [products](https://shopify.dev/docs/api/admin-graphql/latest/queries/products),
+[productCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productCreate),
+[productUpdate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productUpdate),
+[productDelete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productDelete).