@jskit-ai/connectors-catalog 0.1.1

package/docs/oura.md

@@ -0,0 +1,161 @@
+# Oura
+
+Import `ouraProvider` from `@jskit-ai/connectors-catalog/server/oura`. This
+fragment connects each app user's Oura account and reads daily sleep summaries
+and permitted profile fields. It uses OAuth2; personal access tokens were
+deprecated in December 2025. [Current API](https://cloud.ouraring.com/v2/docs).
+
+## Register and configure
+
+1. For new registrations, sign into https://developer.ouraring.com with the
+   account that will own the integration and create an API application. Existing
+   registrations remain editable through Oura Cloud → My Applications at
+   https://cloud.ouraring.com/oauth/applications. Oura's current
+   [support guide](https://support.ouraring.com/hc/en-us/articles/4415266939155-The-Oura-API)
+   distinguishes these portals. The new portal's authenticated form labels
+   were not inspected; the required registration values below are documented.
+2. Enter a name and website describing the application. Configure the exact
+   redirect URI served by the application's backend, including scheme and path.
+3. Copy the assigned Client ID into the integration form. Store the Client
+   Secret in backend Env as `OURA_CLIENT_SECRET`; store the callback URL as
+   `OURA_CALLBACK_URL`.
+4. New applications have a ten-user limit. When ready for a wider audience,
+   submit the application for approval from its application page.
+   [Application registration](https://cloud.ouraring.com/docs/).
+5. Save this configuration, then start consent. The form selects per-user mode
+   and `daily` permission by default. Add `personal` or `email` only when the
+   corresponding profile data is needed. Save configuration, then use the Env
+   links to populate those references. Connect account invokes the configured
+   application setup command; its runtime performs consent and stores grants.
+   Gen3 and later users need active Oura Membership to retrieve API data.
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "oura": {
+      "source": "own",
+      "clientId": "YOUR_OURA_CLIENT_ID",
+      "clientSecretRef": "env:OURA_CLIENT_SECRET",
+      "callbackUrlRef": "env:OURA_CALLBACK_URL"
+    }
+  },
+  "integrations": {
+    "oura": {
+      "provider": "oura",
+      "displayName": "My Oura data",
+      "accountMode": "per-user",
+      "scopes": ["daily"],
+      "authentication": { "method": "oauth2", "registrationRef": "oura" }
+    }
+  }
+}
+```
+
+Consent uses `https://cloud.ouraring.com/oauth/authorize` and exchanges the code
+at `https://api.ouraring.com/oauth/token`. The runtime submits client credentials
+in the form-encoded token request. It retains reduced callback scopes when the
+token response omits them, and serializes refresh because Oura refresh tokens
+are single-use. A declined `daily` permission prevents verification. The runtime
+sends state and an S256 PKCE challenge; Oura's documentation does not establish
+server-side PKCE enforcement, which has not been tested against a live account.
+[OAuth protocol](https://cloud.ouraring.com/docs/authentication).
+
+## Runtime and AI composition
+
+Use ordinary application modules; no template, generator or database is needed:
+
+```js
+import { readFile } from "node:fs/promises";
+import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
+import { createConnectionService, createEnvironmentReferenceResolver } from "@jskit-ai/connectors-core/server";
+import { createFileConnectionStore, createCredentialProtection } from "@jskit-ai/connectors-core/server/file-storage";
+import { ouraProvider } from "@jskit-ai/connectors-catalog/server/oura";
+
+const providers = [ouraProvider];
+const configuration = parseIntegrationConfiguration(await readFile("integrations.json", "utf8"), { providers });
+const protection = createCredentialProtection({
+  keys: { current: Buffer.from(process.env.CONNECTOR_STORAGE_KEY, "base64") },
+  activeKeyId: "current"
+});
+const connections = createConnectionService({
+  configuration, providers,
+  store: createFileConnectionStore({ directory: process.env.CONNECTOR_STATE_DIRECTORY, protection }),
+  resolveReference: createEnvironmentReferenceResolver(),
+  authorize: applicationConnectionPolicy
+});
+```
+
+`applicationConnectionPolicy` is the existing application's authenticated policy.
+It derives the application ID and subject ID from trusted session/operator
+context. Never accept these owner identifiers directly from request input.
+Keep the runtime directory outside exported source and the encryption key stable
+across restarts and backups. A CLI uses the same imports, JSON and local operator
+policy with its registered callback listener.
+
+Call `beginAuthorization({ context, integrationId: "oura" })` to obtain the URL.
+After the user approves, the backend callback supplies the same authenticated
+context and exact callback URL to `completeAuthorization`. Redirect to the
+application after success; never put provider tokens in the browser or chat.
+Use `cancelAuthorization` when abandoning a pending attempt and `disconnect`
+to remove local access. Neither revokes other applications' provider grants.
+
+`invoke({ context, integrationId: "oura", operation: "dailySleep.list", input })`
+reads `/v2/usercollection/daily_sleep`. Inputs are optional `start_date` and
+`end_date` as valid `YYYY-MM-DD` dates, plus opaque `next_token`. Preserve the
+same date range when paging and stop when the returned token is absent or null.
+This fragment supports dates, not date-time input or selectable response fields.
+`personalInfo.read` reads `/v2/usercollection/personal_info` with `personal` or
+`email` consent. It returns only the fields Oura permits. Other Oura permission
+families and operations are outside this fragment.
+[Endpoint schemas](https://cloud.ouraring.com/v2/static/json/openapi-1.37.json).
+
+An Oura grant provides data access; implement application login through the
+application's identity system. The six simulated runtime tests cover consent
+reduction, cancellation, token-response precedence, file persistence, owner
+isolation, refresh rotation, input validation, provider errors and disconnect.
+No live user data or generated application was exercised.
+
+## Application ownership, callbacks and capacity
+
+The documented initial registration workflow is the dashboard. No supported
+public API for creating OAuth client registrations was established in this pass.
+An AI can prepare JSON, callback handlers and runtime composition after an owner
+creates and authorizes the registration; approval remains a provider process.
+
+The application owner creates the provider registration and stores its secret
+in the application's private Env. Public Vibe64, Vibe64 Online and CLI users use
+this same ownership model. The configuration file holds the client ID and Env
+references; the editor does not own the application's grants.
+
+Register the exact callback implemented by the application. For a hosted project,
+start with its assigned application URL and append the implemented callback path.
+Save that same URL through the application's callback Env reference. On a domain
+or host change, update both the provider registration and callback Env if the URL
+changes. Preserve the application's identity and persistent grant store when
+moving it; neither a new editor URL nor a new hosting address creates a new owner.
+See the [callback guide](../../connectors-core/docs/oauth-callbacks.md) and
+[application setup command](../../connectors-core/docs/setup-command.md).
+
+Separate client IDs do not guarantee isolation from user/account limits; verify
+those limits for the approved applications.
+
+
+## Accepted data coverage
+
+The project-owned adapter provides dailySleep.list, sleep.list,
+dailyReadiness.list and dailyActivity.list under daily permission. Supply
+start_date/end_date (YYYY-MM-DD). heartRate.list separately requires heartrate;
+use start_datetime/end_datetime with an explicit timezone. Optional next_token
+is opaque; invoke again explicitly until it is absent. Start cannot exceed end.
+A user may decline heart-rate permission without preventing daily sleep access.
+
+The same service.invoke/configuration/Env/store contract works from a CLI app.
+Other frameworks use their native OAuth client and these Oura V2 endpoints,
+with per-user grants; Vibe64 holds no health-data gateway. The app owns charts,
+refresh scheduling, user access policy and private storage.
+
+**LIMITATIONS:** No continuous sync/webhooks, health dashboard, workouts, tags,
+sessions or SpO2 operations; no coding-chat attachment. Example: fetch sleep and
+readiness history, then build the chart in the app. No live/generated-app proof.
+Source: [Oura V2 API and linked OpenAPI1.37](https://cloud.ouraring.com/v2/docs).

package/docs/paddle.md

@@ -0,0 +1,168 @@
+# Paddle
+
+Import `paddleProvider` from `@jskit-ai/connectors-catalog/server/paddle`.
+This adapter reads a Paddle Billing product catalogue and creates products and prices. Checkout creation,
+merchant activation and payment processing are separate application work.
+
+## Configure access
+
+First [create or sign into your own Paddle account](https://login.paddle.com/signup).
+Follow Paddle's [account signup instructions](https://www.paddle.com/help/start/intro-to-paddle/essentials-to-sign-upcreate-a-paddle-account)
+and complete the requested seller verification in its dashboard. Use a sandbox
+account for testing; a saved sandbox key does not approve your business or enable
+live payments. The merchant is the business receiving payments, not a customer
+or business record created through the billing API.
+
+1. Sign into the intended Paddle sandbox or live account. Open **Developer
+   tools → Authentication → API keys → New API key**.
+2. Enter a descriptive name, choose the `product.read` permission and an expiry
+   appropriate to your application. Add `product.write` for product creation and
+   `price.write` for price creation, and `notification_setting.write` to edit
+   notification destinations. Save the key and copy its secret when shown.
+   This is a backend API key; a frontend client token cannot replace it.
+   [Authentication setup](https://developer.paddle.com/api-reference/about/authentication).
+3. Put the secret in backend Env as `PADDLE_API_KEY`. Save provider `paddle`,
+   mode `shared` or `assistant`, `scopes: []`, and authentication
+   `{ "method": "api-key", "secretRef": "env:PADDLE_API_KEY" }`.
+4. Set `settings.environment` to `sandbox` (the default) or `live`, matching the
+   account that issued the key. The editor exposes the same choice as
+   **Environment**. Sandbox calls use `https://sandbox-api.paddle.com`; live
+   calls use `https://api.paddle.com`. Requests specify `Paddle-Version: 1`.
+   [API environments](https://developer.paddle.com/api-reference/about).
+5. Call `connectApiKey` to verify product access. A changed environment requires
+   verification again. Local disconnect removes local access state; revoke a
+   key in the Paddle dashboard when remote access should end.
+
+## Runtime and AI composition
+
+`products.list` calls `GET /products`. Inputs are `per_page` (1–200, default
+50), `after` (the previous page's final product ID), and `status` (`active` by
+default or `archived`). Results retain `data` and `meta.pagination`, including
+`has_more`. Extract the next cursor rather than treating a returned URL as an
+arbitrary authenticated request destination.
+[Product listing](https://developer.paddle.com/api-reference/products/list-products).
+
+`products.create` calls `POST /products`. Supply `name` (1–200 characters),
+`tax_category` from the provider's supported categories, and optionally
+`description` (up to 2048 characters). It creates the product only; retain its
+returned `data.id` for the next operation.
+[Create product](https://developer.paddle.com/api-reference/products/create-product/).
+
+`prices.create` calls `POST /prices`. Supply `product_id`, `description`
+(2–500 characters), and `unit_price: { amount: "1200", currency_code: "USD" }`.
+Amounts are integer strings in the currency's smallest unit. The currency must
+be supported by Paddle. Omit `billing_cycle` for a one-time price, or supply
+`{ interval: "month", frequency: 1 }` for a monthly recurring price. Other
+intervals are `day`, `week` and `year`, with a positive integer frequency.
+[Create price](https://developer.paddle.com/api-reference/prices/create-price/).
+
+Product and price writes are separate requests, not an atomic transaction.
+If price creation fails after product creation, retain the product ID and
+resolve the failed price step rather than recreating the product. The adapter
+does not retry failed writes. A network failure can leave an unknown outcome;
+inspect the merchant catalogue before deciding whether to repeat the action.
+These operations create catalogue entries; they do not charge a customer.
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) and the file
+connection store. An AI can compose a product picker from this operation without
+creating transactions. Unsupported settings and excessive page sizes fail
+locally. Tests exercise sandbox/live routing, verification, result validation,
+file restart, ownership and failure handling with simulated HTTP responses.
+
+## Edit a webhook destination
+
+In Paddle, open **Developer tools → Notifications**, choose the destination's
+menu, then **Edit destination**. The same change can be made by calling
+`webhooks.update` with its `notification_setting_id` (`ntfset_…`) and the fields
+to change. At least one change is required. Supported fields are `description`,
+`destination`, `active`, `api_version`, `include_sensitive_fields`,
+`subscribed_events`, and `traffic_source` (`platform`, `simulation`, or `all`).
+The provider validates the destination against its existing URL/email type.
+[Update API](https://developer.paddle.com/api-reference/notification-settings/update-notification-setting/).
+
+Send the **complete desired event list** when changing `subscribed_events`;
+omitted events are unsubscribed. Omit the field to preserve subscriptions.
+The adapter keeps omitted settings unchanged and removes `endpoint_secret_key`
+from the result. Store the signing secret separately in the app's backend Env
+when provisioning the destination. The application owns the HTTP receiver,
+signature verification and event handling. This operation neither creates
+that receiver nor confirms that deliveries succeed.
+[Dashboard instructions](https://developer.paddle.com/webhooks/about/notification-destinations/).
+
+## Domain approval and going live
+
+`checkoutDomains.get` accepts `domain_id` (`chedom_…`) and reads the provider's
+approval status. Grant `checkout_domain.read` to the API key. In assistant mode
+this operation uses the `goLive.check` policy. Preserve the returned status:
+`pending_review`, `in_review`, `action_required`, `rejected`, or `approved`.
+An approved domain does not establish seller verification, working checkout,
+correct app entitlements or successful webhook delivery.
+[Domain status API](https://developer.paddle.com/api-reference/checkout-domains/get-checkout-domain/).
+
+For production, use Paddle's dashboard to complete seller setup. Configure
+**Checkout → Checkout settings** with the approved website's payment link.
+Review **Catalog → Products** and **Catalog → Taxable categories**, and configure
+payouts under **Business account → Payouts → Payout settings**. Create live keys
+and a frontend client token under **Developer tools → Authentication**, plus
+live webhook destinations under **Developer tools → Notifications**. Replace
+sandbox catalogue IDs and credentials in the app. Sandbox IDs do not identify
+live products. The connector does not copy catalogues on deployment or inspect
+legal pages, and never labels a connected key “ready to accept payments.”
+[Go-live guide](https://developer.paddle.com/build/go-live-checklist/).
+
+## Automation and application ownership
+
+The documented initial key setup is through the dashboard. This research has
+not established an API that creates the initial merchant account or API key.
+The [public API reference](https://developer.paddle.com/api-reference/) does not
+establish a supported merchant-provisioning path for this connector. Create the
+merchant through the provider signup flow above; do not substitute the customer
+or business creation endpoints. Any partner-only onboarding would require a
+separate documented provider agreement and implementation. It is not a hidden
+requirement for this project's runtime or export.
+Paddle documents automatic key rotation through AWS Secrets Manager for keys
+created with the Rotatable option; this fragment does not provision that
+integration. [Rotation workflow](https://developer.paddle.com/api-reference/about/rotate-api-keys).
+
+An AI can prepare configuration and runtime wiring after credential bootstrap.
+The merchant owner still handles account access, verification and activation.
+Sandbox/live is a testing/production choice, not a free/paid quota partition.
+Separate keys in one merchant account do not establish separate account limits
+or balances. The application owner supplies credentials for its intended merchant
+account; the editor does not supply a merchant account or shared capacity.
+
+
+## Assistant permissions and payment workflow ownership
+
+The provider declares the captured enable, recommendation, product/price,
+batch-product, go-live, read/write and webhook-edit permission controls.
+`products.list` maps to `api.read`. In assistant execution mode the connection
+service enforces its configured ask/always/never policy before invocation.
+The host must bind an approval to the authenticated caller and exact arguments;
+a policy cannot grant missing Paddle permissions.
+
+For host-owned actions, use `authorizeAssistantAction` with the declared action
+and exact input before executing the host's implementation. This method only
+authorizes; it does not create a merchant, product, price, payment or webhook.
+The adapter supplies product listing, product creation, price creation and
+existing webhook-destination updates.
+The [catalogue recipe](../patterns/paddle-catalogue/PATTERN.md) composes
+product-with-price and batch workflows with a partial-success report. Domain
+approval can be read explicitly; full go-live readiness and arbitrary read/write
+actions remain outstanding and must not be advertised as executable merely because
+permission controls exist. No unrestricted API URL or write proxy is exposed.
+JSKIT owns the JavaScript configuration/runtime contract; Laravel applications
+use their own Paddle SDK and authorization implementation. Vibe64 edits the
+project configuration and does not become the merchant account owner.
+
+## Full application payments
+
+This connector's operations are only part of a billing implementation. For
+checkout, subscriptions, feature access, renewal credits and durable catalogue
+mappings, read [payments-core](../../payments-core/README.md) and its
+[standalone composition guide](../../payments-core/docs/standalone.md). These
+JavaScript libraries work from ordinary app code or a CLI without Vibe64 or
+Genesis. Other frameworks consume the [portable contract](../../payments-core/docs/contract.md)
+and its static examples using their own runtime libraries. Keep provider setup
+from this guide; do not substitute a successful connection check for working
+checkout, verified webhooks or merchant approval.

package/docs/perplexity.md

@@ -0,0 +1,85 @@
+# Perplexity
+
+Import `perplexityProvider` from
+`@jskit-ai/connectors-catalog/server/perplexity`.
+The adapter verifies credentials with async-request summaries. The app-owned native-client recipe below uses this same saved slot for cited answers and streaming.
+
+## Configure access
+
+1. Sign into the Perplexity API console. Open **Projects** and create or select
+   the project that should own these credentials.
+2. Open **API Keys**, generate the initial key, and copy its value before
+   navigating away. Store it in backend Env as `PERPLEXITY_API_KEY`.
+3. Save provider `perplexity`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication
+   `{ "method": "api-key", "secretRef": "env:PERPLEXITY_API_KEY" }`.
+4. Run `connectApiKey` to verify the authenticated async-request listing.
+   Provider revocation remains separate from local disconnect.
+   [Key management](https://docs.perplexity.ai/docs/admin/api-key-management).
+
+## Runtime and AI composition
+
+`requests.list` calls `GET https://api.perplexity.ai/v1/async/sonar` using
+Bearer authorization. The result contains `requests` and may contain
+`next_token`. This fragment exposes the initial page only: the reference read
+in this pass did not specify a continuation query parameter, so none is
+invented. It does not submit or resume a generation job.
+[Async list](https://docs.perplexity.ai/api-reference/async-sonar-get).
+
+`models.list` calls `GET /v1/models` and returns the provider's `object: list`
+envelope. That endpoint is public and therefore is not used to verify the key.
+Both operations accept no input. Model names remain provider data rather than
+hard-coded choices. [Model list](https://docs.perplexity.ai/api-reference/models-get).
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) with this
+provider and the private file store. AI-written source can present model
+choices or previous request statuses. For answer generation and streaming, use the supplied app-owned recipe below.
+
+## Automation and application ownership
+
+After the console project and initial key exist, an authorized AI can create
+additional keys with `POST /generate_auth_token`, Bearer auth and
+`{ "token_name": "application-name" }`. Capture `auth_token` once into Env.
+`POST /revoke_auth_token` accepts the old `auth_token` for retirement after
+replacement. These administrative operations are not invoked by the fragment.
+[Provisioning API](https://docs.perplexity.ai/docs/admin/api-key-management).
+
+The application owner supplies its own token and checks overlapping project and
+account limits. Token labels alone do not isolate capacity. Billing remains
+between that owner and Perplexity; this adapter does not assign platform credits.
+
+Tests verify authenticated checking, request paths, result validation, key
+rotation, restart, isolation and HTTP errors without live service use.
+
+## Complete native-client recipe
+
+Use [perplexity-answer.js](../patterns/ai-connections/example/perplexity-answer.js)
+from the existing AI-connections pattern. Your app supplies its native SDK factory:
+
+```js
+import OpenAI from "openai"; // installed and owned by the application
+import { createPerplexityAnswers } from "./perplexity-answer.js";
+const answer = createPerplexityAnswers({ configuration, authorize,
+  createClient: options => new OpenAI(options) });
+const response = await answer({ context, integrationId: "research",
+  model: "sonar", question: "What does the source report?" });
+// response.choices[0].message.content, response.citations, response.search_results
+const chunks = await answer({ context, integrationId: "research", model: "sonar",
+  question: "Summarize the source", stream: true, signal });
+for await (const chunk of chunks) { /* render delta text; retain final citations */ }
+```
+
+The slot is provider perplexity, authentication api-key and your own secretRef;
+there is no second AI configuration or model catalogue to maintain. The app's
+policy authorizes the exact question/model/mode before Env access. Keys resolve
+on every call, so rotation applies without rewriting source. CLI apps use the
+same recipe; other frameworks read the slot and use their native SDK directly.
+
+**LIMITATIONS:** No premade research/chat screen, persistent conversation, budget
+manager, Agent API orchestration or automatic coding-chat attachment. Example:
+a backend can request a cited answer; the app owns rendering and spending rules.
+The adapter's async-history listing still only reads its initial page. Live
+provider behavior and generated-app execution are unproven.
+
+[Native compatibility](https://docs.perplexity.ai/docs/sonar/openai-compatibility)
+and [streaming](https://docs.perplexity.ai/docs/sonar/pro-search/stream-mode).

package/docs/pipedrive.md

@@ -0,0 +1,120 @@
+# Pipedrive
+
+Import `pipedriveProvider` from `@jskit-ai/connectors-catalog/server/pipedrive`.
+The adapter reads the authenticated profile using an API token or project-owned
+OAuth registration, and provides the CRM operations listed below.
+
+## Configure access
+
+1. Sign into Pipedrive and switch to the intended company. A user has a distinct
+   token in each company.
+2. Open the top-right account menu, **Company settings → Personal preferences → API**.
+3. Copy the existing API token. If the API section is missing, follow Pipedrive's
+   enablement guidance with the company administrator.
+4. Store it in backend Env as `PIPEDRIVE_API_KEY`. Only one active user token
+   exists for that company; regenerating it can affect other connected tools.
+5. Save provider `pipedrive`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication `{ "method": "api-key", "secretRef": "env:PIPEDRIVE_API_KEY" }`.
+6. Verify with `connectApiKey`. Manage the original credential through the API
+   settings page. [Token setup](https://pipedrive.readme.io/docs/how-to-find-the-api-token).
+
+## OAuth setup
+
+1. Use a developer sandbox account. Open the account menu → Developer Hub →
+   Create an app. Choose private for an unlisted integration or public for a
+   Marketplace listing; the type cannot be changed later.
+2. In Basic info enter the app name and exact project callback, then Save.
+   Pipedrive permits one callback per registration. The generated application
+   must serve it; its initial hosting URL is the suggested origin.
+3. OAuth & access scopes contains Client ID and Client secret. Copy the ID
+   into the project registration and store the secret in private Env, for
+   example `PIPEDRIVE_CLIENT_SECRET`. Store the registered callback in
+   `PIPEDRIVE_CALLBACK_URL`. Registration authentication is `client_secret_basic`.
+4. This adapter needs only the default `base` permission. Leave configuration
+   `scopes: []`: permissions are selected in Pipedrive's registration rather
+   than dynamically selected here. CRM reads/writes require the corresponding
+   implementation and provider permissions.
+5. A private draft is limited to its own company. Use Change to live to allow
+   other companies to install it. Public Marketplace publication has a separate
+   review process. [Private registration](https://pipedrive.readme.io/docs/marketplace-registering-a-private-app),
+   [Developer Hub states](https://pipedrive.readme.io/docs/developer-hub).
+6. Save authentication `{ "method": "oauth2", "registrationRef": "pipedrive" }`
+   and an own registration with Client ID, the two Env references and Basic
+   authentication. Use `per-user` for independent application-user grants,
+   `shared` for a shared application account, or `assistant` for assistant use.
+7. Start `beginAuthorization`, redirect to consent, and complete the exact
+   callback with `completeAuthorization`. The user selects their company and
+   allows installation. This connects CRM access, not application login.
+
+The provider's [OAuth contract](https://pipedrive.readme.io/docs/marketplace-oauth-authorization)
+uses confidential Basic authentication and form-encoded token requests. The
+adapter uses the existing runtime's non-PKCE confidential flow. Each grant
+retains the validated `api_domain` returned by the provider. Only a bare HTTPS
+company subdomain of `pipedrive.com` is accepted. API calls use that company's
+`/api/v1/users/me` with a bearer token. Refresh must return the same domain;
+a change requires reconnection. A custom project domain changes the registered
+callback, not the connected Pipedrive company.
+
+## Runtime and CLI composition
+
+In API-token mode, `profile.read` sends `GET https://api.pipedrive.com/v1/users/me` with
+`x-api-token`. It takes no operation inputs and returns the `success`/`data`
+envelope, including user and available company metadata. The verifier requires
+`success: true` and a numeric user ID; malformed successful HTTP responses are
+not accepted as connections. The global discovery endpoint is documented by
+Pipedrive's [company-domain guide](https://pipedrive.readme.io/docs/how-to-get-the-company-domain).
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) with this
+provider. Do not send the token in query parameters or store it in source JSON.
+Connection metadata belongs to the runtime's private file directory.
+
+## Automation and application registrations
+
+An AI can prepare files and validate requests after the owner supplies their
+token or OAuth registration. No ordinary-account API for
+unattended app registration was established in this pass.
+
+The application owner supplies its authorized user token through private Env.
+Separate configuration names still reference the same user/company capacity.
+The project owns its registration, callback handler, Env secrets and private
+grants. Vibe64 configures these values; it does not operate a central gateway.
+JSKIT supplies the JavaScript runtime; Laravel implements the same provider
+contract with its own framework. Disconnect deletes the local grant; revoke
+provider access separately by uninstalling the app in Pipedrive.
+OAuth fixtures cover two-company routing, refresh rotation after restart,
+callback replay, rejected API destinations and company changes on refresh.
+Local fixtures cover headers, file-store restart, rotation, tenant isolation,
+invalid responses, forbidden requests and rate limits. No Pipedrive account or
+record was accessed.
+## CRM operations
+
+Set settings.companyDomain for API-token record calls: copy `acme` from
+`https://acme.pipedrive.com`. OAuth instead uses its stored provider-issued company
+address; settings cannot override that grant. Changing settings requires recheck.
+Missing domain fails before sending CRM traffic; profile checking remains global.
+
+Use list/get/create/update for deals, persons, organizations, activities and
+leads. Pipelines support list/get only. Standard objects use v2; leads use v1.
+List inputs limit/cursor (v2) or limit/start (leads); preserve additional_data
+and explicitly request subsequent pages. Creation requires title (deal/lead),
+name (person/organization), subject (activity). Leads also need person_id or
+organization_id. Update takes numeric id (lead UUID) and changed fields.
+Persons support emails/phones arrays of value, primary and label. Deals accept
+value/currency/status, owner/person/org/stage IDs; activities accept links,
+done and due_date/due_time. Provider validates actual company IDs/field values.
+
+In Developer Hub OAuth & access scopes choose deals:read/full, contacts:read/full,
+activities:read/full for the selected operations, then reconnect. These are
+registration-controlled capabilities, not dynamically selected scope checkboxes.
+Provider permissions and the app's own record/write policy both apply. Verification
+never creates a CRM record; uncertain writes are not automatically replayed.
+
+CLI uses service.invoke with the same JSON/Env and authorized local operator.
+Other frameworks use these endpoints with their native client and company-bound
+OAuth grant. No central Vibe64 credential gateway.
+**LIMITATIONS:** No full CRM UI, pipeline administration, custom fields/bulk import,
+attachments, webhooks or coding-chat attachment. Example: create a contact and
+follow-up deal; build the sales dashboard in the application. No live/generated-app proof.
+[Records](https://developers.pipedrive.com/docs/api/v1/Deals),
+[permissions](https://pipedrive.readme.io/docs/marketplace-scopes-and-permissions-explanations),
+[company routing](https://developers.pipedrive.com/tutorials/get-deals-pipedrive-api).

package/docs/polar.md

@@ -0,0 +1,63 @@
+# Polar
+
+Import `polarProvider` from `@jskit-ai/connectors-catalog/server/polar`.
+This is the Polar.sh commerce service. The fragment reads products through an
+Organization Access Token; merchant activation and payment creation are separate.
+
+## Configure access
+
+1. Open the intended organization in the Polar dashboard, then **Settings**.
+   Scroll to **Developers → New Token**.
+2. Give the token an application-specific name and expiration. Select
+   `products:read`, create the token and copy it into backend Env as `POLAR_OAT`.
+   [Token setup](https://polar.sh/docs/integrate/oat).
+3. Save provider `polar`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication `{ "method": "api-key", "secretRef": "env:POLAR_OAT" }`.
+   The requested permission was assigned when creating the token, not through
+   an OAuth consent flow in this configuration.
+4. Choose `settings.environment: "sandbox"` (default) or `"production"`.
+   Sandbox has separate organizations, data and tokens. Its origin is
+   `https://sandbox-api.polar.sh`; production uses `https://api.polar.sh`.
+   [Environments and authentication](https://polar.sh/docs/api-reference/introduction).
+5. Call `connectApiKey` to verify product access. A customer access token does
+   not replace this organization credential. Changing environments requires
+   verification again. Local disconnect does not revoke the remote token.
+
+## Runtime and AI composition
+
+`products.list` reads `GET /v1/products/`, including the trailing slash to avoid
+an authenticated redirect. Inputs are `page` (default 1), `limit` (1–100, default
+10), optional product-name `query`, `is_archived` and `is_recurring` booleans.
+The result retains `items` and `pagination` (`total_count`, `max_page`). Increment
+the page until `max_page`. Additional array, metadata and sorting filters are
+outside this operation's supported inputs.
+[Product listing](https://polar.sh/docs/api-reference/2026-04/products/list-products).
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) and file store
+to compose a product catalogue or picker. Creating checkout sessions, processing
+webhooks and connecting other merchants through OAuth are further application
+work. Replace Env credentials on rotation and revoke obsolete tokens in Polar.
+Tests cover pagination, sandbox/production routing, invalid settings, credential
+replacement, persistence and failures with simulated provider responses.
+
+## Automation and application ownership
+
+The documented OAT bootstrap is the organization dashboard; this pass does not
+establish a public token-creation API. Polar does document organization creation
+through `POST /v1/organizations/` with `organizations:write`, a name and slug.
+That needs existing authorized access and does not complete merchant review or
+activate payments. [Organization API](https://polar.sh/docs/api-reference/organizations/create).
+
+An AI can prepare configuration and compose runtime calls after bootstrap.
+Each application supplies a token belonging to its intended organization and
+billing owner. Tokens within one organization share its applicable limits;
+sandbox/production separates test and real commerce. The editor supplies no
+shared registration, token pool or merchant account.
+
+## Existing-scope closeout — 13 September 2026
+
+The existing app-owned Organization Access Token adapter lists a Polar.sh product catalogue in sandbox or production, with bounded page/name/archive/recurrence filters and environment-bound verification.
+
+This is NOT the captured personal builder MCP/billing-context experience: coding-assistant attachment and MCP authentication/tools remain deferred. No managed payments, merchant onboarding, checkout, subscription/customer/order management, refunds, webhooks, credits/entitlements, catalogue writes/synchronization or customer login is shipped by this adapter. No merchant OAuth, customer-access-token mode, token provisioning, extra array/metadata/sort filters or automatic pagination. Changing environment requires verification; local disconnect does not revoke the token. The app supplies its own organization token, permissions, UI and access policy. To extend: implement the separately deferred editor tool bridge for the captured use case; require a separate scope decision before adding an app billing product. Do not infer Stripe/Paddle parity from this catalogue reader. No live provider account, provider registration, paid request or generated-application execution was tested. No new editor coding-assistant tool attachment is claimed. Other frameworks use the same project configuration and their own native tools; JSKIT is optional.
+
+2 Polar-specific plus 2 shared environment/pagination source checks passed, and the same 4 installed-package checks passed on September 13. Existing shared token/environment form evidence is retained; no fresh browser run.