@jskit-ai/connectors-catalog 0.1.1

package/docs/dbt-semantic-layer.md

@@ -0,0 +1,175 @@
+# dbt Semantic Layer
+
+Import `dbtSemanticLayerProvider` from
+`@jskit-ai/connectors-catalog/server/dbt-semantic-layer`. The library verifies an environment, browses metadata and queries metric values. CLI and Vibe64 use the
+same file and validators. Saving does not contact dbt or run a warehouse query.
+
+## Provider setup
+
+1. Sign into the dbt account owning the project. Confirm Semantic Layer access,
+   configured metrics, a supported warehouse and a deployment environment.
+2. Open **Account settings → Settings → Projects**, select your project, then
+   **Semantic Layer → Configure Semantic Layer**. Choose the deployment
+   environment containing those metrics and save.
+3. Under **Credentials & service tokens**, choose **Add Semantic Layer
+   credential**. Supply a warehouse identity allowed to read the source schemas.
+4. Map a new service token to that credential. Name it for this application and
+   grant **Semantic Layer Only** and **Metadata Only** permissions. Save.
+5. Copy the one-time token. In Vibe64 enter `env:DBT_SERVICE_TOKEN` in
+   **Service token reference**, save configuration, and use **Set credential in
+   Env** to paste and save the token as `DBT_SERVICE_TOKEN`. CLI users supply the
+   same backend environment variable; source stores only its reference.
+6. Copy the GraphQL hostname and Environment ID from the Semantic Layer
+   connection details. Use the GraphQL host, not the JDBC connection string.
+7. Save and choose **Connect account / Verify again**. **Check connection** only reads saved status. CLI hosts call `connectApiKey`.
+   Verification reads the environment's data-platform dialect.
+
+The provider's account plan, roles and warehouse credentials remain required.
+[Semantic Layer setup](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl)
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "metrics": {
+      "provider": "dbt-semantic-layer",
+      "displayName": "Warehouse metadata",
+      "accountMode": "shared",
+      "scopes": [],
+      "settings": {
+        "host": "semantic-layer.cloud.getdbt.com",
+        "environmentId": "70506183142324"
+      },
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:DBT_SERVICE_TOKEN"
+      }
+    }
+  }
+}
+```
+
+The Environment ID is positive decimal **text**, locally bounded to 38 digits.
+Never convert it through a JavaScript number. `assistant` ownership is also
+available; neither mode connects separate accounts for application users.
+
+## Hosts and operations
+
+The transport sends Bearer-authenticated POST requests to
+`https://<host>/api/graphql`, injecting the configured `environmentId` as a
+`BigInt!` variable. Hosts support North America, EMEA, APAC, dbt single-tenant
+and multi-cell patterns. Copy the actual hostname; these patterns do not prove
+that a particular account exists. Arbitrary domains, URLs, paths and ports are
+rejected. [GraphQL API](https://docs.getdbt.com/docs/dbt-apis/sl-graphql)
+
+| Operation | Inputs | Selected result |
+|---|---|---|
+| `queries.create` | `metrics`, optional `groupBy` and `where`, `limit` (default 100, max 10000) | `data.createQuery.queryId` |
+| `queries.get` | `queryId`, `pageNum` (default 1) | `data.query.status`, `totalPages`, decoded `jsonResult` |
+| `environment.read` (verification) | None | `data.environmentInfo.dialect` |
+| `metrics.list` | Paging and optional search | `data.metricsPaginated`, with name, description and type |
+| `dimensions.list` | Required `metrics: [{ name }]`, plus paging/search | `data.dimensionsPaginated`, with name, description and type |
+| `savedQueries.list` | Paging and optional search | `data.savedQueriesPaginated`, with name and description |
+
+Paging inputs are `pageNum` (default 1, positive GraphQL integer) and `pageSize`
+(default 20, local limit 100). `search` is at most 512 characters. Dimension
+reads accept 1–100 metric names, each at most 512 characters. Page results keep
+`items`, `pageNum`, `pageSize`, `totalItems` and `totalPages`. The original
+GraphQL envelope is returned. Empty lists and nullable descriptions are valid.
+
+Each call makes one request. No automatic paging, polling or retries occur.
+The fixed documents keep caller data in variables. Environment and host are
+configuration values, never operation overrides. Unknown operations, fields,
+malformed pages and partial GraphQL errors fail before data is returned.
+HTTP 401 requires reconnection; 403 reports denied permission; 429 reports
+rate limiting. GraphQL error text is not used to guess authentication state
+or exposed to the caller. Host, environment and token-reference changes require
+reverification; updating the existing secret binding supports token rotation.
+Disconnect removes local connection state, not the provider token.
+
+## Application and CLI wiring
+
+Compose this provider with the existing connection service, your file-backed
+store, Env resolver and authorization callback. Vibe64 writes the same JSON;
+it is not needed at runtime. After explicit token verification:
+
+```js
+const started = await connections.invoke({
+  context, integrationId: "metrics", operation: "queries.create",
+  input: {
+    metrics: [{ name: "order_total" }],
+    groupBy: [{ name: "metric_time", grain: "MONTH" }],
+    limit: 100
+  }
+});
+const page = await connections.invoke({
+  context, integrationId: "metrics", operation: "queries.get",
+  input: { queryId: started.data.createQuery.queryId, pageNum: 1 }
+});
+// If pending, schedule a bounded later check using the SAME query ID.
+// If SUCCESSFUL, render page.data.query.jsonResult.data using its table schema.
+```
+
+Other frameworks use their native HTTP client with the same host, exact string
+Environment ID and backend Env token. They send the documented GraphQL requests
+and implement their own result parsing/access policy. No JSKIT dependency or
+Vibe64 service is required for those applications.
+
+## Public, Online and universal URLs
+
+This service-token variant has **no OAuth registration or callback URL**.
+There is no universal URL to enter in dbt for it. The customer's VM or custom
+domain can invoke the same backend library with the same configuration. Its
+identity and authorized environment must remain stable when the address changes.
+
+Each application owner supplies the customer's token and selected environment
+through its own configuration and private Env. Its backend enforces access and
+usage limits. Separate tokens do not establish independent account or warehouse
+capacity; confirm any required provider arrangement. The adapter does not
+provision provider accounts or warehouse capacity.
+
+## Automation assessment
+
+| Work | Feasibility |
+|---|---|
+| Write or edit configuration and wire the runtime | AI can use these exports, schema and ordinary file storage with externally supplied references. |
+| Read metadata and query metric values | Implemented API operations; a valid customer token/environment are required. |
+| Create two OAuth applications | Not applicable to the captured service-token flow. |
+| Provision warehouse identities, dbt credentials and service tokens | Account-admin setup is required. The reviewed setup instructions do not establish a complete provisioning API; do not claim automated creation. An authorized operator can follow the portal steps above. |
+| Choose account capacity or grant access | Requires the owner's account and warehouse decisions. No change is made by saving a form. |
+
+## Current limits and evidence
+
+Queries accept 1–100 metrics (`name`, optional `alias`), up to 100 dimensions
+(`name`, optional `grain`: DAY/WEEK/MONTH/QUARTER/YEAR), and up to 20 trusted
+`where: [{sql}]` filters. For example, group `order_total` by `metric_time` at
+MONTH grain and filter with `{{ Dimension('metric_time') }} >= '2026-01-01'`.
+The fixed GraphQL document uses variables, but SQL templates remain executable
+provider expressions: the backend must construct trusted filters and enforce
+customer access. Never interpolate arbitrary app-user text into them.
+
+Submit once using `queries.create`; retain its ID and call `queries.get` at a
+bounded interval while pending. SUCCESSFUL returns a decoded pandas TABLE object:
+rows are in `jsonResult.data`, column metadata in `jsonResult.schema.fields`.
+Request each page explicitly through `totalPages`; the provider normally uses
+1024 rows per page. Local JSON pages are bounded to 5 MiB/1024 rows. FAILED raises
+a generic error; inspect dbt for details. No retries or background polling are
+performed, and a timed-out submission may still execute and consume warehouse
+capacity. The app owns submission deduplication, deadlines and authorization.
+
+**LIMITATIONS:** dbt recommends JSON for testing/validation because of its
+performance cost. This path supports small metric tables; large production
+analytics should use native dbt/Arrow tooling. Arrow decoding, SQL compilation,
+saved-query execution, webhooks and app-user login are not supplied. For example,
+an app can fetch monthly revenue and render its own chart, but this connector
+does not build the chart or a continuous warehouse dashboard. Editor
+Codex/OpenCode attachment remains deferred. Personal access
+tokens are another documented provider option; the captured service-token setup
+is the supported initial onboarding journey.
+
+Controlled HTTP/file tests cover configuration, host restrictions, precise IDs,
+metadata, empty pages, ownership, restart, rotation, malformed responses,
+permission failures, cancellation and timeout. Live account setup, actual data
+access and generated applications are not exercised. Editor form proof is
+recorded separately when the installed package has passed browser checks.

package/docs/elevenlabs.md

@@ -0,0 +1,102 @@
+# ElevenLabs
+
+Import `elevenlabsProvider` from `@jskit-ai/connectors-catalog/server/elevenlabs`.
+This connector discovers voices/models, generates audio and creates Instant Voice Clones.
+
+## Set up access
+
+1. Select the intended ElevenLabs workspace. Choose **Developers** in the
+   sidebar and open **API Keys**.
+2. Create a named key. Keep restrictions enabled and grant read access to the
+   User read and Voices read. Add Models read and Text to Speech for synthesis; Voices write is required only for cloning.
+3. Set an available credit limit and expiry appropriate for the application.
+   Copy the key when created; the full value is not displayed later.
+4. Store the value outside source as `ELEVENLABS_API_KEY`. The configuration slot
+   uses provider `elevenlabs`, mode `shared` or `assistant`, empty `scopes`, and
+   `authentication: { "method": "api-key", "secretRef": "env:ELEVENLABS_API_KEY" }`.
+5. Save and choose **Connect account / Verify again**, or call `connectApiKey` from your CLI host. **Check connection** only reads saved status. Verification reads the account without generating audio; it does not prove speech/cloning permissions.
+   Edit/revoke keys through the key's **•••** menu. See
+   [API-key setup](https://elevenlabs.io/docs/help-center/technical/how-do-i-authorize-myself-using-an-api-key).
+
+## Runtime and AI composition
+
+`account.read` uses `GET /v1/user` as the authenticated verification request.
+`voices.list` uses `GET /v2/voices`, with `search`, `page_size` (1–100, default
+10), and `next_page_token`. Results preserve the pagination envelope, including
+`has_more` and `next_page_token`. Requests carry `xi-api-key`. See
+[Account](https://elevenlabs.io/docs/api-reference/user/get) and
+[Voices](https://elevenlabs.io/docs/api-reference/voices/search).
+
+Compose the [API-key source pattern](../patterns/api-key-connection/PATTERN.md)
+with this provider and an application authorizer. Keep resource ownership in
+the application. A CLI edits the same portable JSON as Vibe64; neither requires
+a database to store connection state.
+
+## Provisioning automation and capacity
+
+An AI can prepare source/configuration and wire these operations once a key
+is provided; generation and cloning require explicit application authorization. This pass has not verified automated key/service-account issuance
+for every plan; use console-assisted setup for the initial credential. Dedicated
+service accounts can isolate resources where available, but that alone does not
+prove separate workspace credits. See [Provider security guidance](https://elevenlabs.io/docs/eleven-api/guides/how-to/best-practices/security).
+
+The application owner supplies its workspace/service credential through private
+Env and verifies the actual billing and concurrency boundaries. Retain provider
+key limits. Two key names in one workspace do not create independent capacity.
+
+Fixtures cover both endpoints, the custom header, cursor encoding, page limits,
+encrypted file restart, rotation and permission/rate-limit failures. No real
+ElevenLabs requests or audio generation were performed.
+
+## Speech and Instant Voice Cloning
+
+- `models.list`: `GET /v1/models`; choose a model with `can_do_text_to_speech`.
+- `speech.create`: `POST /v1/text-to-speech/{voiceId}`; required `voiceId`,
+  `model_id` and `text` (1–5000 characters). Optional `language_code` and bounded
+  `voice_settings` (stability, similarity_boost, style, use_speaker_boost, speed).
+  Output choices: mp3_44100_128 (default), mp3_22050_32, pcm_16000, ulaw_8000.
+  The result contains `bodyBase64`, `contentType`, `size`; decode it on the
+  backend and return audio through an authorized route. PCM/µ-law are raw formats,
+  not universally browser-playable files. MP3 is suitable for an HTML audio player.
+- `voices.clone`: `POST /v1/voices/add`, multipart `files` plus `name`, optional
+  `description` and `remove_background_noise` (false by default). The portable
+  input supplies 1–5 files as `{name, contentType, base64}`, total at most 16 MiB,
+  with canonical base64 and a maximum 12 MiB encoded per file. The app must supply
+  `consentConfirmed: true` after obtaining speaker permission; this local flag
+  is not sent as a provider field. Response `requires_verification: true` means
+  the voice is not yet ready. Complete provider verification; never bypass it.
+
+[Speech API](https://elevenlabs.io/docs/api-reference/text-to-speech/convert),
+[Instant clone API](https://elevenlabs.io/docs/api-reference/voices/ivc/create).
+For console cloning, open Voices > Add a new voice > Instant Voice Clone,
+provide clear samples, a name and confirm rights. An eligible plan/voice slot
+is required; [Instant cloning is available from Starter](https://help.elevenlabs.io/hc/en-us/articles/13313587528849-What-is-My-Voices).
+
+```js
+const audio = await connections.invoke({ context, integrationId: "voice",
+  operation: "speech.create", input: {
+    voiceId: selectedVoiceId, model_id: selectedModelId, text: approvedText
+  }
+});
+const bytes = Buffer.from(audio.bodyBase64, "base64");
+// Serve bytes through your app's authenticated audio route, using contentType.
+```
+
+The generated app owns authorization, voice selection, samples, storage, credit
+limits and playback. Other frameworks use their native HTTP/multipart clients
+with the same backend Env key and documented endpoints; no JSKIT runtime or
+Vibe64 gateway is needed. API-key setup has no OAuth client or callback URL.
+
+**LIMITATIONS:** Audio is buffered up to 16 MiB; it is not low-latency streaming.
+Use native ElevenLabs streaming for live conversation or larger outputs.
+Professional Voice Cloning, realtime agents, regional residency and provider
+verification workflows are not implemented here. For example, an app can generate
+an appointment announcement with an authorized cloned voice, but configuring this
+connector does not create a phone agent or let Vibe64's coding assistant use it.
+Editor assistant attachment is deferred. A failed or timed-out POST may already
+have consumed credits or created a clone; no automatic retry is performed.
+
+Focused fixtures additionally verify playable audio bytes/content type, malformed
+and oversized responses, clone multipart/consent/verification status, denied
+permissions, rate limiting and uncertain submissions. No live audio, account or
+generated app was used.

package/docs/figma.md

@@ -0,0 +1,132 @@
+# Figma remote MCP
+
+Checked against Figma's public documentation and OAuth discovery on 9 September
+2026. This fragment connects an assistant owner's account, discovers tools and
+invokes an explicitly authorized tool. It uses the remote HTTP server, not the
+desktop MCP server or a personal access token for Figma's REST API.
+
+## Prerequisites and registration
+
+Figma currently admits clients listed in its MCP catalogue. A new client must
+request approval through the waitlist linked from the
+[MCP introduction](https://developers.figma.com/docs/figma-mcp-server/).
+The registration endpoint's existence does not remove that requirement.
+
+1. Open that introduction and follow **join the waitlist** in the client-access
+   notice. Supply the intended assistant client and usage details requested by
+   Figma. Wait for acceptance; this package cannot approve a client.
+2. Choose the callback implemented by your backend or CLI host. For your own
+   application, this is its actual HTTPS callback, or a loopback callback where
+   accepted. The host must retain the pending owner and state through consent.
+3. After approval, use Vibe64's **OAuth client registration** section to copy
+   the endpoint and JSON body into an HTTP client and send one POST with
+   Content-Type application/json. Alternatively invoke `registerFigmaClient`
+   once from a trusted setup command.
+   It sends `client_name`, the exact callback, the authorization-code/refresh
+   grant types and `mcp:connect` to Figma's advertised registration endpoint.
+   It requests confidential client authentication using `client_secret_post`.
+4. Put the returned client ID in `registrations.figma.clientId`. Store the
+   returned secret and callback in your host's existing secret/environment
+   facilities; place only references in `clientSecretRef` and `callbackUrlRef`.
+5. In Vibe64, open **Integrations → Add Figma**. Enter **Client ID**,
+   **Client secret reference** and **Callback URL reference**. Keep **Assistant
+   access** and **Use Figma MCP tools**, then save. Use **Set credential in Env** for the returned secret and **Set
+   callback in Env** for the exact registered URL. Saving edits the same JSON
+   a CLI user writes; it does not register the client or start consent.
+6. Your host calls `beginAuthorization` and opens its URL. Sign into Figma and
+   review the consent screen. Its callback calls `completeAuthorization` for
+   the original authenticated owner. The runtime verifies tool discovery before
+   saving a connected grant.
+
+There is no separate REST-app dashboard step in this MCP registration fragment.
+Figma's [remote-server instructions](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/)
+show the consent UI for supported clients. Do not copy another client's ID to
+bypass the approval process.
+
+## Runtime and CLI composition
+
+Import `figmaProvider` and `registerFigmaClient` from
+`@jskit-ai/connectors-catalog/server/figma`. Use the
+[assistant OAuth pattern](../patterns/assistant-mcp-oauth/PATTERN.md) with the
+existing connection service, environment resolver and encrypted file store.
+
+```js
+const registration = await registerFigmaClient({
+  clientName: "My design assistant",
+  callbackUrl: configuredCallback
+});
+```
+
+The setup caller authorizes this operation and stores `registration.clientSecret`
+securely. Do not print the result or run registration for each sign-in. On an
+ambiguous failure, check with the provider before trying to create another client.
+
+The provider's resource is `https://mcp.figma.com/mcp`. Authorization uses
+`https://www.figma.com/oauth/mcp`; exchange/refresh use
+`https://api.figma.com/v1/oauth/token`. Discovery advertises an authorization
+response issuer, which the runtime requires and validates. PKCE, state,
+single-use attempts, refresh, isolation and token storage belong to the shared
+connection implementation.
+[Authorization metadata](https://api.figma.com/.well-known/oauth-authorization-server),
+[resource metadata](https://mcp.figma.com/.well-known/oauth-protected-resource).
+
+Call `tools.list` first; use the returned schemas to validate inputs for
+`tools.call`. The host must approve the exact name and arguments, including file
+and node identity. `mcp:connect` is a broad MCP permission, not a read-only
+guarantee. A host that only needs design reads should disallow write tools in its
+own policy. Preserve the tool's `isError` result and surface provider failures.
+Discovery does not prove access to a particular design.
+
+## Connection ownership and callbacks
+
+Register the real callback implemented by the runtime that owns this connection.
+For an application integration, use the application's assigned hosting URL as
+the initial origin and its implemented callback path. Store the exact callback
+in its Env reference and provider registration. A domain change requires updating
+both values if the callback URL changes; retain the application identity and its
+persistent grants when moving hosts. Public Vibe64, Online and CLI users supply
+their own registrations through this same contract.
+See the [callback guide](../../connectors-core/docs/oauth-callbacks.md).
+
+The registration and grants belong to the application or explicitly authorized
+assistant host consuming Figma. Provider approval and usage quotas still apply;
+separate client IDs do not establish separate capacity or broader permissions.
+
+## Automation assessment and limits
+
+The helper can automate the documented client-registration request and field
+validation after eligibility is established. AI can prepare configuration,
+callback handling and permitted tool policy. Provider approval, account sign-in
+and user consent require the appropriate human/provider action. No account,
+registration, consent or tool call was performed against Figma in these tests.
+
+Tests use controlled OAuth/MCP responses with real encrypted file persistence.
+They exercise issuer binding, refresh, owner isolation, replay, invalid inputs,
+tool authorization, cancellation, safe failures and registration behavior.
+Local desktop MCP, automatic chat attachment, login and resources/prompts
+are not implemented by this fragment.
+
+## Design context and topology
+
+After connection, discover the current tool schemas and explicitly authorize the
+selected file and node before calling `get_design_context`. A Figma frame link
+identifies that selection. Preserve returned text, images and tool errors for
+the authorized assistant host. The returned context is provider-owned, not a
+fixed JSKIT design schema; fixtures demonstrate consumption rather than asserting
+an immutable live tool signature. The host chooses the target framework and
+performs code generation itself.
+
+**LIMITATIONS:** This supplies remote MCP only. Installed Vibe64 and Online can
+both use the remote server with their own approved registration. Desktop MCP is
+local to the machine running Figma Desktop and the consuming client: on Online,
+127.0.0.1 means the VPS, not the user's laptop. Native desktop clients may configure
+Figma Desktop independently; no tunnel/proxy is provided here. Government-only
+desktop deployments are outside this remote connector.
+
+Editor coding-assistant attachment is deferred. For example, an explicitly wired
+assistant host can receive an authorized booking-card layout and screenshot, but
+saving Figma in Vibe64 does not yet let Codex/OpenCode reproduce that frame.
+App-user login, Make resources/prompts and a visual Figma editor are not supplied.
+Other frameworks use a native MCP/OAuth client and the same config/Env contract;
+PHP/other runtime code does not belong in JSKIT. Provider approval remains external;
+new-client registration is a guided setup/helper request, not automatic admission.