@jskit-ai/connectors-catalog 0.1.1

package/README.md

@@ -0,0 +1,192 @@
+# Connector catalogue
+
+Browser-safe definitions are exported from `@jskit-ai/connectors-catalog/shared`.
+Import a provider individually from `@jskit-ai/connectors-catalog/server/<id>`;
+the id is the linked guide's filename without `.md`.
+HTTP and MCP providers compose with `createConnectionService` from connectors-core; each
+contains request validation and a small useful operation set, not application
+business workflows. There is no automatic provider installation or activation.
+
+Each application owns its registration, callback, credentials and grants. Read
+the core package's [callback guide](../connectors-core/docs/oauth-callbacks.md)
+and [application setup contract](../connectors-core/docs/online-setup.md), which
+apply to hosted editors, installed editors and CLI use. There is no shared
+Vibe64 provider registration or token gateway.
+
+## Finding setup instructions from a CLI or coding agent
+
+Start with the selected provider's guide in `docs/<provider-id>.md`, linked
+below. It describes credential acquisition, required permissions, environment
+choices and the adapter's supported operations. Read only the selected
+provider's recipe and shared contracts it references. A configured credential
+is not proof that the application's requested feature is implemented.
+
+`integrations.json` is application-owned source; secret values belong in the
+application's Env or private grant storage. The same files can be authored by
+hand, by a coding agent or by an editor. Genesis is optional: when used, selected
+Stack guidance should lead to these same documents, while the application
+records its actual environment requirements and implemented commands.
+
+For full Stripe/Paddle checkout, subscriptions, features and usage credits,
+continue to [application-owned payments](../payments-core/README.md) and its
+[standalone composition](../payments-core/docs/standalone.md). The narrow
+catalogue connector alone does not implement billing. Other technologies can
+read the [static payment contract](../payments-core/docs/contract.md), schema
+and examples without executing JavaScript; their own framework owns runtime
+implementation. An editor management command is optional for standalone CLI
+use, and does not replace application authorization.
+
+Definitions can expose `verificationFields` with `name`, `label`, `hint` and `required` for
+non-secret text inputs used by a provider's check operation. Sheets, Docs and
+Slides expose their resource IDs this way. Excel supplies a workbook drive item
+ID, SharePoint a site-search term, PostHog a flag-evaluation identity, Maps an
+address and X a public username. Maps and X field hints identify provider usage
+charges before the explicit check. A UI passes entered values through
+`verificationInput` on Connect; CLI callers supply the same operation input.
+These are check parameters, separate from source configuration and credentials.
+Provider request validation remains authoritative.
+
+| Provider | Export | Initial operations | Authentication |
+|---|---|---|---|
+| [AI](docs/ai.md) | `createAiConnectionResolver` | Static catalogue and authorized SDK parameters; app-owned inference | Free public Zen default, administrator Env key or private individual grant |
+| [Wiz](docs/wiz.md) | `createWizScanner` | Authorised source-directory scan, policy verdict and report; separate CLI runtime | Own Cognito service account; installed Wiz v1 CLI |
+| [Shopify](docs/shopify.md) | `shopifyProvider` | `products.list`, `products.create`, `products.update`, `products.delete`; assistant policies | Organization client credentials or existing Admin API token |
+| [Confidence Flags](docs/confidence-flags.md) | `confidenceFlagsProvider`, `registerConfidenceClient` | `tools.list`, `tools.call`; explicit client setup | Assistant OAuth for flag management |
+| [Confidence Exp](docs/confidence-exp.md) | `confidenceExpProvider`, `registerConfidenceClient` | `tools.list`, `tools.call`; explicit client setup | Assistant OAuth for experiment analysis |
+| [Lightspeed](docs/lightspeed.md) | `lightspeedProvider` | `products.list`, `customers.list`, `outlets.list`, `sales.list`, `inventory.list` | Own X-Series OAuth registration and store prefix |
+| [Microsoft Fabric](docs/microsoft-fabric.md) | `microsoftFabricProvider` | `connection.check`, `schema.types`, `graphql.execute` | Tenant-specific user consent or service principal; one GraphQL endpoint |
+| [X (Twitter)](docs/x-twitter.md) | `xTwitterProvider` | `users.lookup`, `users.posts` | App-only bearer token; public reads |
+| [Snowflake](docs/snowflake.md) | `snowflakeProvider` | `databases.list` | Account-specific custom OAuth; optional role and bounded metadata pages |
+| [Workday](docs/workday.md) | `workdayProvider` | `workers.me`, `workers.list` | Per-user confidential tenant OAuth; Staffing v7 worker reads |
+| [Gemini Enterprise](docs/gemini-enterprise.md) | `geminiEnterpriseProvider` | `engine.get`, `search` | Google OAuth; configured project, region and engine; shared search identity |
+| [Wix](docs/wix.md) | `wixProvider` | `sites.list` | Own account API key; explicit site pages |
+| [TikTok](docs/tiktok.md) | `tiktokProvider` | `profile.read`, `profile.extended`, `profile.stats`, `videos.list` | Own confidential Web OAuth; optional profile/statistics/video permissions |
+| [LinkedIn](docs/linkedin.md) | `linkedinProvider` | `profile.read`, `posts.create` | Own OAuth; approved member text publishing; reconnect unless refresh is approved |
+| [Google Ads](docs/google-ads.md) | `googleAdsProvider` | `customers.listAccessible`, `customers.listClients`, `reports.search` | Own Google OAuth plus developer token or approved Cloud organization |
+| [Salesforce](docs/salesforce.md) | `salesforceProvider` | `limits.read`, `objects.list`, `objects.describe`, `query.read`, `query.next` | Own confidential OAuth, My Domain and production/sandbox settings |
+| [Firebase Cloud Messaging](docs/firebase-cloud-messaging.md) | `firebaseCloudMessagingProvider` | `connection.check`, `messages.validate`, `messages.send`; public web configuration helper | Explicit service-account JSON reference and target project; optional web push |
+| [dbt Semantic Layer](docs/dbt-semantic-layer.md) | `dbtSemanticLayerProvider` | `environment.read`, `metrics.list`, `dimensions.list`, `savedQueries.list` | Customer service token, GraphQL host and exact text Environment ID; metadata only |
+| [Databricks](docs/databricks.md) | `databricksProvider` | `jobs.list`, `jobs.get` | Custom user OAuth application or service principal; per-workspace URL |
+| [Hex](docs/hex.md) | `hexProvider`, `registerHexClient` | `tools.list`, `tools.call`; explicit client setup | Assistant OAuth; standard, EU and HIPAA endpoints |
+| [Granola](docs/granola.md) | `granolaProvider` | `notes.list`, `notes.get`, `folders.list`, `transcripts.list` | Own personal/workspace API key; MCP is separate |
+| [Zoho Books](docs/zoho-books.md) | `zohoBooksProvider` | `organizations.list`, `contacts.list`, `invoices.list` | Own regional web OAuth registration; explicit organisation selection |
+| [Zoho CRM](docs/zoho-crm.md) | `zohoCrmProvider` | `users.current`, `leads.list`, `contacts.list`, `accounts.list`, `deals.list` | Own regional web OAuth registration |
+| [Wave](docs/wave.md) | `waveProvider` | `user.read`, `businesses.list`, `customers.list`, `invoices.list` | Own web OAuth registration |
+| [Semrush](docs/semrush.md) | `semrushProvider` | `projects.list`, `projects.get` | Own V4 API key with read permission |
+| [Xero](docs/xero.md) | `xeroProvider` | `connections.list`, `organisation.read`, `contacts.list`, `invoices.list` | Own web OAuth registration, Basic client authentication |
+| [Resend](docs/resend.md) | `resendProvider` | Domains, transactional sending, contacts/segments and draft/review/send broadcasts | Own API key, Full access |
+| [Firecrawl](docs/firecrawl.md) | `firecrawlProvider` | `credits.read`, `pages.scrape` | Own team API key |
+| [Gmail](docs/gmail.md) | `gmailProvider` | `profile.read`, `messages.list`, `messages.get` | Own OAuth registration |
+| [Google Drive](docs/google-drive.md) | `googleDriveProvider` | `files.list` | Own OAuth registration |
+| [Google Sheets](docs/google-sheets.md) | `googleSheetsProvider` | `spreadsheets.get`, `values.get` | Own OAuth registration |
+| [Google Docs](docs/google-docs.md) | `googleDocsProvider` | `documents.get` | Own OAuth registration |
+| [Google Slides](docs/google-slides.md) | `googleSlidesProvider` | `presentations.get` | Own OAuth registration |
+| [Google Search Console](docs/google-search-console.md) | `googleSearchConsoleProvider` | `sites.list` | Own OAuth registration |
+| [Airtable](docs/airtable.md) | `airtableProvider` | `bases.list` | Own personal access token |
+| [Notion](docs/notion.md) | `notionProvider` | Search, page/block reads and writes, data-source queries; separate MCP tools | Own internal token, REST OAuth or separate MCP client |
+| [Brevo](docs/brevo.md) | `brevoProvider` | `contacts.list` | Own API key |
+| [ElevenLabs](docs/elevenlabs.md) | `elevenlabsProvider` | `account.read`, `voices.list` | Own API key |
+| [GitHub API](docs/github-api.md) | `githubApiProvider` | `account.read`, `repositories.list` | Own personal access token |
+| [Apify](docs/apify.md) | `apifyProvider` | `actors.list` | Own API token |
+| [Calendly](docs/calendly.md) | `calendlyProvider` | `profile.read`, `eventTypes.list` | Own personal access token |
+| [HubSpot](docs/hubspot.md) | `hubspotProvider` | Contact/deal list/get/create/update, relationships and pipeline reads | Own private/static token or project OAuth |
+| [Linear](docs/linear.md) | `linearProvider` | `profile.read`, `issues.list` | Own personal API key |
+| [Pipedrive](docs/pipedrive.md) | `pipedriveProvider` | Profile; deals, people, organizations, activities, leads and pipeline reads; basic record create/update | Own user/company API token |
+| [GitLab API](docs/gitlab-api.md) | `gitlabApiProvider` | `profile.read`, `projects.list` | Own GitLab.com personal access token |
+| [Tally](docs/tally.md) | `tallyProvider` | `forms.list` | Own API key |
+| [Contentful](docs/contentful.md) | `contentfulProvider` | `entries.list` | Own Content Delivery key, space and environment |
+| [Asana](docs/asana.md) | `asanaProvider` | `workspaces.list` | Own personal access token |
+| [Microsoft Outlook](docs/microsoft-outlook.md) | `microsoftOutlookProvider` | `folders.list`, `inbox.list` | Own delegated OAuth registration |
+| [Microsoft OneDrive](docs/microsoft-onedrive.md) | `microsoftOneDriveProvider` | `items.list/get`, `files.upload` | Own delegated OAuth registration |
+| [Microsoft Excel](docs/microsoft-excel.md) | `microsoftExcelProvider` | `worksheets.list`, `ranges.get/update`, `sessions.create/close` | Own delegated OAuth registration |
+| [Microsoft Teams](docs/microsoft-teams.md) | `microsoftTeamsProvider` | Team/channel/chat reads and message/reply sends | Own organizational OAuth registration |
+| [Microsoft OneNote](docs/microsoft-onenote.md) | `microsoftOneNoteProvider` | `notebooks.list`, `sections.list`, `pages.list/content/create/append` | Own delegated OAuth registration |
+| [Microsoft Word](docs/microsoft-word.md) | `microsoftWordProvider` | `items.list`, `items.get` | Own delegated OAuth registration |
+| [Microsoft PowerPoint](docs/microsoft-powerpoint.md) | `microsoftPowerPointProvider` | `items.list`, `items.get` | Own delegated OAuth registration |
+| [Microsoft SharePoint](docs/microsoft-sharepoint.md) | `microsoftSharePointProvider` | `sites.search` | Own organizational OAuth registration |
+
+| [Stripe](docs/stripe.md) | `stripeProvider` | `balance.read` | Own restricted/secret API key |
+| [Replicate](docs/replicate.md) | `replicateProvider` | Account/hardware, model schema, prediction submit/poll/cancel | Own API token |
+| [Sentry](docs/sentry.md) | `sentryProvider` | `organizations.list` | Own Sentry.io personal token |
+| [incident.io](docs/incident-io.md) | `incidentIoProvider` | Incidents/follow-ups, alert resolution, schedule reads, catalogue entries | Own API key |
+| [Fireflies](docs/fireflies.md) | `firefliesProvider` | `profile.read`, `transcripts.list` | Own API key |
+
+| [HeyGen](docs/heygen.md) | `heygenProvider` | `profile.read`, `voices.list` | Own API key |
+| [Perplexity](docs/perplexity.md) | `perplexityProvider` | `requests.list`, `models.list` | Own project API key |
+| [Supabase](docs/supabase.md) | `supabaseProvider` | `projects.list` | Own Management API personal token |
+| [Google Analytics](docs/google-analytics.md) | `googleAnalyticsDefinition` (shared configuration) | Framework-owned Google tag | Public Measurement ID |
+| [BigQuery](docs/bigquery.md) | `bigqueryProvider` | `projects.list` | Own OAuth registration |
+| [Paddle](docs/paddle.md) | `paddleProvider` | `products.list` | Own sandbox/live API key |
+| [Mailgun](docs/mailgun.md) | `mailgunProvider` | `domains.list` | Own US/EU account API key |
+| [Fireworks AI](docs/fireworks-ai.md) | `fireworksAiProvider` | `accounts.list` | Own API key with account read access |
+| [GatewayAPI](docs/gatewayapi.md) | `gatewayApiProvider` | `balance.read` | Own Global/EU API token |
+| [Polar](docs/polar.md) | `polarProvider` | `products.list` | Own sandbox/production organization token |
+| [Storyblok](docs/storyblok.md) | `storyblokProvider` | `space.read`, `stories.list` | Own public/preview space token, five regions |
+| [Twitch](docs/twitch.md) | `twitchProvider` | `token.validate`, `profile.read`, `channels.followed` | Own application-specific confidential OAuth registration |
+| [Slack](docs/slack.md) | `slackProvider` | `auth.test`, `channels.list`, `groups.list`, `directMessages.list`, `groupMessages.list` | Own OAuth registration, connected user or installed bot |
+| [Oura](docs/oura.md) | `ouraProvider` | Daily/detailed sleep, readiness, activity, heart rate and profile reads | Own per-user OAuth registration |
+| [Algolia](docs/algolia.md) | `algoliaProvider` | `indices.list`, `index.search` | Own application ID and backend API key; optional frontend key reference |
+| [Twilio](docs/twilio.md) | `twilioProvider` | `calls.list` | Own regional Account SID, Standard API Key SID and secret |
+| [Gong](docs/gong.md) | `gongProvider` | `users.list` | Own company access key and secret, optional company API origin |
+| [PostHog](docs/posthog.md) | `posthogProvider` | `flags.evaluate`, `events.capture` | Own public project token, numeric project ID and EU/US region; explicit verification subject |
+| [Chargebee](docs/chargebee.md) | `chargebeeProvider` | `customers.list` | Own site name and API key with transactional-data read access |
+| [Ashby](docs/ashby.md) | `ashbyProvider` | `jobs.list` | Own organization key with Jobs: Read access |
+| [Lexware](docs/lexware.md) | `lexwareProvider` | Accounting resource reads, article/voucher pages, `invoices.createDraft` | Own private Public API key with selected read/create permissions |
+| [Sevdesk](docs/sevdesk.md) | `sevdeskProvider` | `contacts.list` | Own account API token, raw Authorization header |
+| [Apollo.io](docs/apollo-io.md) | `apolloIoProvider` | `accounts.search` | Own workspace API key scoped to saved-account search |
+| [Attention](docs/attention.md) | `attentionProvider` | `conversations.list` | Own organization API key |
+| [Telegram](docs/telegram.md) | `telegramProvider` | `profile.read`, `webhook.read` | Own bot token |
+| [KLIPY](docs/klipy.md) | `klipyProvider` | Clip/GIF/sticker/existing-emoji trending and search | Own app key; generation unavailable |
+| [Mapbox](docs/mapbox.md) | `mapboxProvider` | `token.read`, `geocoding.forward`, `geocoding.reverse`, `directions.get` | Backend token or browser-only public-token configuration |
+| [Logo.dev](docs/logo-dev.md) | `createLogoDevImageUrl` (client export) | Public image URL construction | Publishable image key; no server connection grant |
+| [Google Maps Platform](docs/google-maps-platform.md) | `googleMapsPlatformProvider` | `geocoding.forward`, `geocoding.reverse` | Server API key, optional browser-key reference and an explicit verification address |
+| [WooCommerce](docs/woocommerce.md) | `woocommerceProvider` | `products.list`, `orders.list` | Own HTTPS store, consumer key and secret reference |
+| [PrestaShop](docs/prestashop.md) | `prestashopProvider` | `products.list`, `orders.list` | Own HTTPS store and Webservice API key reference |
+| [ClickHouse](docs/clickhouse.md) | `clickhouseProvider` | `connection.check`, `tables.list`, `columns.list`, `rows.list` | Own HTTPS endpoint; Basic database credentials or explicit no-credentials mode |
+| [WordPress (self-hosted)](docs/wordpress-self-hosted.md) | `wordpressSelfHostedProvider` | `users.me`, `posts.list` | Own HTTPS site, username and Application Password reference |
+| [WordPress.com](docs/wordpress-com.md) | `wordpressComProvider` | `profile.read`, `sites.list`, `posts.list` | Own OAuth registration, verified client and permissions |
+| [n8n](docs/n8n.md) | `n8nProvider` | `tools.list`, `tools.call` | Assistant MCP access token, own instance URL |
+| [Sanity](docs/sanity.md) | `sanityProvider` | `tools.list`, `tools.call` | Assistant API token, hosted MCP endpoint |
+| [Inngest](docs/inngest.md) | `inngestProvider` | `apps.list`, `functions.list`, `events.send` | Separate Signing Key and Event Key references |
+| [Canva](docs/canva.md) | `canvaProvider`, shared `createCanvaClientMetadata` | `tools.list`, `tools.call`; public metadata builder | Assistant OAuth, metadata URL, approved callback, no client secret |
+| [Clay](docs/clay.md) | `clayProvider` | `identity.read`, `searches.create`, `searches.next` | User/workspace Public API key |
+| [Figma](docs/figma.md) | `figmaProvider` | `tools.list`, `tools.call`; explicit `registerFigmaClient` setup | Approved confidential OAuth client |
+| [Miro](docs/miro.md) | `miroProvider` | `tools.list`, `tools.call`; explicit `registerMiroClient` setup | Own MCP OAuth client, selected team |
+| [Atlassian](docs/atlassian.md) | `atlassianProvider`, `registerAtlassianClient` | `tools.list`, `tools.call`; explicit client setup | Assistant OAuth, Rovo MCP v2, own confidential client |
+| [Amplitude](docs/amplitude.md) | `amplitudeProvider`, `registerAmplitudeClient` | `tools.list`, `tools.call`; explicit client setup | Assistant OAuth, US/EU, own confidential client |
+| [AWS S3](docs/aws-s3.md) | `awsS3Provider` | `objects.list`, `objects.downloadUrl`, `objects.uploadUrl` | Explicit AWS key/optional STS token |
+| [AWS Athena](docs/aws-athena.md) | `awsAthenaProvider` | `workgroup.get`, `query.start`, `query.status`, `query.results`, `query.cancel` | Explicit AWS key/optional STS token |
+| [Amazon Redshift](docs/amazon-redshift.md) | `amazonRedshiftProvider` | `tables.list`, `table.describe`, `query.start`, `query.status`, `query.results`, `query.cancel` | Explicit AWS key/optional STS token; serverless or provisioned |
+
+The MCP providers use the official MCP SDK through a server-only transport.
+They initialize and list tools to verify transport access, then expose explicit
+tool calls under the existing connection policy. Discovery does not prove
+permission to execute every tool. Read the [assistant OAuth pattern](patterns/assistant-mcp-oauth/PATTERN.md) for
+Amplitude/Atlassian/Canva setup and the [assistant MCP pattern](patterns/assistant-mcp/PATTERN.md)
+before exposing calls. These definitions cannot select shared or per-user
+application mode. OAuth discovery, assistant attachment, resources, prompts and
+local stdio are not part of these initial fragments.
+
+The definitions provide names, account modes, permissions and setup text to the
+shared configuration fields. API-key values belong in the environment or secret
+store; `integrations.json` stores references. Use the file connection store for
+text-based runtime persistence. SQL is an explicit application choice.
+
+See the [API-key connection pattern](patterns/api-key-connection/PATTERN.md) for
+library wiring usable from ordinary Node code and a manually composed CLI.
+The [OAuth file-connection pattern](patterns/oauth-connection/PATTERN.md) covers
+consent and callbacks with the same text-based runtime storage.
+The [Microsoft guide](docs/microsoft-oauth.md) adds delegated OAuth wiring,
+registration automation and provider-specific account/permission requirements.
+Focused runtime tests cover the providers' requests, result validation,
+credential changes, isolation, errors and disconnect. Provider calls in those
+tests are simulated; live service use and sample-app generation are outside
+this delivery's test scope. Managed service credentials and sharing grants
+remain host-owned capabilities; an own key is not a managed subscription.
+
+Logo.dev uses the [public-image pattern](patterns/public-image/PATTERN.md) and
+its client library export. Its `runtimeKind: "public-resource"` metadata
+distinguishes URL construction from the server adapters above. Image delivery
+is observed in the browser; constructing a URL never records Connected.
+
+The [AWS pattern](patterns/aws-storage-queries/PATTERN.md) composes the signed S3 and Athena libraries with the same file configuration and host authorization.

package/docs/ai-upstream-notices.md

@@ -0,0 +1,51 @@
+# AI catalogue upstream notices
+
+The bundled snapshot is derived from models.dev data and OpenCode’s public-access rule. Both are MIT licensed. See `src/shared/ai-models.json` for retrieval date, URLs and source hashes. No upstream code executes at runtime.
+
+## models.dev
+
+MIT License
+
+Copyright (c) 2025 models.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## OpenCode
+
+MIT License
+
+Copyright (c) 2025 opencode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/ai.md

@@ -0,0 +1,191 @@
+# AI connections and a static model catalogue
+
+This integration supplies configuration and authorized connection parameters.
+The application's AI library makes requests directly to its chosen provider.
+There is no JSKIT or Vibe64 inference gateway, token resale, conversation engine,
+coding-agent runtime, or automatic paid fallback.
+
+## Ownership
+
+| Owner | Responsibility |
+| --- | --- |
+| JSKIT `connectors-catalog` | Static provider/model data, settings schema, free-access classification and Node credential resolver |
+| JSKIT `connectors-web` | Reusable Vue configuration fields, including searchable model selection |
+| Vibe64 | Edit the project's portable `integrations.json`; manage administrator secrets through its existing Env system |
+| Vibe64 Online | Supply the same editor and Env facilities; it supplies no AI credit or shared commercial AI identity |
+| Generated application | Authenticate and authorize its users, own credentials and individual connection screens, choose its AI SDK, execute requests and handle provider failures |
+| Other frameworks | Read the same configuration or map it into their native configuration; use their own libraries and private credential storage |
+
+JSKIT is a JavaScript library for Node applications. A Laravel application does
+not install JSKIT, Node, OpenCode or Vibe64. Its backend can read the selected
+model and `env:NAME` reference and use its own environment/configuration and AI
+client. Framework-independent facts in this guide are usable by its coding AI;
+PHP code and a parallel PHP package are not part of JSKIT.
+
+## Default and catalogue
+
+Import `aiCatalogue`, `listAiModels`, `getAiModel`, `aiAccessLabels` and
+`DEFAULT_AI_MODEL` from `@jskit-ai/connectors-catalog/shared/ai`.
+
+The one-time 10 September 2026 extraction contains 213 provider records and
+7,614 model records from models.dev, the catalogue used by OpenCode. There is
+no runtime fetch, synchronization job, subprocess or OpenCode dependency.
+The raw-source hashes and source URLs are in the bundled `ai-models.json`;
+[upstream MIT notices](ai-upstream-notices.md) accompany it. Updates require
+deliberate review and a new package release.
+
+`listAiModels()` hides deprecated entries and sorts free choices first, with
+`opencode/big-pickle` first. `includeDeprecated: true` exposes retained upstream
+history; `providerId`, `access` and `configurableOnly` filter the list.
+Models retain limits, modality and cost metadata as dated information, not a
+promise of current availability or a billing calculator. An explicit unknown
+or deprecated model fails validation; it is never replaced automatically.
+
+| Classification | Meaning |
+| --- | --- |
+| `free-no-setup` | Active Zen entry with zero declared input, output and other cost fields, covered by OpenCode's published public access rule |
+| `free-with-connection` | Zero declared costs, but a connection is required or no public access rule has been established |
+| `paid` | Declared positive input or output charges |
+| `unknown` | Insufficient pricing information; check the provider |
+
+The snapshot's seven active public choices are Big Pickle, MiMo-V2.5 Free,
+Ling3.0 FlashFin Free, Nemotron 3 Ultra Free, Nemotron 3.5 Lightning Free,
+Muse Spark 1.2 Contributor Free and Muse Spark 1.3 Contributor Free.
+This is a source-derived eligibility list, **not live inference verification**.
+Provider capacity, free offers and data-use terms can change. A failure stays
+with the selected provider/model; the application decides how to explain it.
+
+Zen's no-account protocol uses the fixed string `public` in its API-key
+position. The resolver supplies it. Nobody needs to enter it, create an account
+or create an environment variable for this mode. The Muse models use the
+OpenAI Responses SDK route, whereas Big Pickle uses OpenAI-compatible chat;
+the model's `sdkPackage` preserves that distinction.
+
+The initial configuration form and resolver support regular direct API-key
+routes for OpenCode Zen, Z.AI, OpenAI, Anthropic, DeepSeek, Google, OpenRouter,
+Groq, Mistral, xAI, Cerebras, Together AI and Perplexity. Other upstream records
+remain available as `connection: "framework"` metadata. Cloud identity,
+regional endpoints, coding subscriptions and special authentication require
+their framework's own configuration; their presence in the catalogue does not
+claim that a URL and API key can configure them.
+
+## Portable configuration and Env
+
+This is enough to select the no-setup default:
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "suggestions": {
+      "provider": "ai",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "none" },
+      "settings": { "model": "opencode/big-pickle" }
+    }
+  }
+}
+```
+
+For an administrator-funded model, select `authentication.method: "api-key"`
+and `authentication.secretRef: "env:APP_AI_API_KEY"`. Store the **value** in the
+existing Env screen or the application's normal private environment. Vibe64's
+existing launch/deployment environment mechanism supplies it to the backend;
+this integration adds no token delivery service. Do not use `VITE_` or another
+browser-exposed environment prefix. The JSON and source control contain only
+the variable's name.
+
+`createAiConnectionResolver({ configuration, authorize, resolveReference? })`
+is imported from `@jskit-ai/connectors-catalog/server/ai`. It uses the existing
+environment-reference resolver by default. `resolve({ context, integrationId })`
+returns `{ providerId, model, sdkPackage, baseURL?, apiKey, access }` **to backend
+code only**. An absent `baseURL` means use the named provider SDK's normal
+endpoint. Pass the result to an explicitly installed SDK adapter; never
+dynamically install a package or send the result through a browser route.
+
+The application must implement `authorize(context, request)` and return a
+trusted `{ applicationId, subjectId }`, or deny access. It receives operation
+`ai.resolve`, the integration ID and the configured account mode. Derive
+identity from a server-authenticated session or trusted CLI operator, never
+from request-supplied owner IDs. Check who can consume the shared account.
+Authorize edits to the configuration and Env separately as administrator work.
+
+Secrets are resolved on every call, so rotation or deletion takes effect without
+changing source. Missing or invalid bindings fail without leaking their values.
+Saving the form means **configured**, not **connected** or **verified**.
+
+## Individual app accounts
+
+Use `accountMode: "per-user"` and a reference such as `account:personal-ai`.
+The app supplies `resolveReference(reference, owner, slot)`, where `owner` is
+the authorized application/user identity and `slot` includes integration ID,
+account mode and provider ID. Look up only that user's grant for that provider
+and integration. Bind stored keys to all those identities; do not resolve a
+reference against another app's or another provider's credentials.
+
+The app owns authenticated key entry, verification, encrypted private storage,
+replacement and disconnect. JSKIT's existing encrypted file store is available
+to Node apps that choose file storage; this resolver creates no database or
+second store. A shared `env:` reference is rejected in individual-account mode.
+Disconnect removes that user's grant; it must not affect another user.
+
+Changing providers in the form removes the previous key reference. Existing
+editor coding-agent credentials are never inherited. A provider-supported
+OAuth-to-key flow can be implemented by the app before storing its own grant;
+this initial integration does not implement OAuth or a login screen for every
+AI service. Do not repurpose Codex or Claude coding-subscription OAuth tokens
+as general app-inference credentials.
+
+## Provider setup and automation
+
+There are no `vibe64-online`/`vibe64-public` OAuth registrations or universal
+callbacks for this AI integration. Regular keys belong to the app administrator
+or individual app user and are billed directly by that provider.
+
+For the no-setup default: choose AI, keep Big Pickle selected and save. No
+provider-side action is needed. For API-key routes, follow the provider's current
+dashboard documentation linked in `aiCatalogue.providers[].documentationUrl`:
+
+1. The account owner signs in to the provider and selects the organization or
+   project that should own usage. This is a human account/terms/billing step.
+2. Open the provider's API-key management screen and create a dedicated key
+   for this application. Choose applicable project restrictions and limits.
+3. Copy the value directly into the app's Env or authenticated personal-key
+   screen. Save only its reference in the integration configuration.
+4. Choose a model on that same provider route. Configure the app's SDK using
+   the selected model's protocol. Verification and inference belong to the app.
+
+For **Z.AI**, open [API keys](https://z.ai/manage-apikey/apikey-list), create a
+regular API key, store it in Env, and select `zai/glm-4.7-flash`. Its regular API
+base is `https://api.z.ai/api/paas/v4`. GLM-4.7-Flash is listed free but needs a
+key; full GLM-4.7 is paid. The Coding Plan endpoint is not this app-inference
+route.
+
+For **Zen paid access**, follow [Zen setup](https://opencode.ai/docs/zen/),
+create an account/key and meet its billing requirements before choosing a paid
+model. For **OpenRouter**, the app may separately implement the provider's
+[OAuth PKCE key-creation flow](https://openrouter.ai/docs/guides/overview/auth/oauth);
+it still stores the resulting user-owned key privately. Other dashboards may
+offer administrative provisioning APIs, but this slice does not assume or
+automate them. AI can wire environment names, configuration and native SDKs;
+it cannot create somebody's account, accept terms or supply their billing
+authorization merely by editing this JSON.
+
+## Evidence and limits
+
+Focused tests cover snapshot integrity, free/default classification, strict
+selection, authorized environment and individual-key resolution, rotation,
+disconnect, redacted failures and SDK parameter handoff. Browser fixtures cover
+the editor's default, searchable model change, credential ownership, persistence
+and responsive layout. These tests perform no live inference, provider login,
+account creation or generated-application execution.
+
+## Existing-scope closeout — 13 September 2026
+
+A static, attributed September 10 provider/model catalogue, searchable free/paid model configuration and a backend-only authorized credential/SDK-parameter resolver. The default is the snapshot's Zen Big Pickle no-account route; administrator keys resolve through Env, and individual keys through an app-supplied user/provider-scoped reference resolver.
+
+No inference engine, streaming, tools, conversation storage, provider OAuth/login screens, account/key provisioning, live credential verification, usage metering, billing, token resale or Vibe64 AI gateway. No automatic SDK installation, catalogue updates, model replacement or paid fallback. Only the 13 explicitly supported direct-key routes are configurable; other catalogue entries are framework metadata, not implemented cloud/coding-subscription authentication. Model availability, pricing/free classification and endpoint operation are dated source information, not live proof; even no-setup choices can be unavailable or capacity-limited. Detailed provider-specific personal-key entry, verification, encrypted storage, rotation/disconnect and authorization remain application work; the resolver only consumes those bindings. The app/framework owns SDK installation, protocol selection, requests, errors and UI. Generic key-creation guidance and linked provider documentation are supplied; bespoke audited login/key-creation screens for every catalogue provider are not. To extend: deliberately refresh the static snapshot, improve selected provider-specific instructions, and wire any desired app-native key-entry/inference features. This intentionally differs from Lovable managed AI; Vibe64 coding-agent credentials and runtime remain separate.
+
+10 source and 10 installed-package tests passed on September 13, proving snapshot/default selection, rejected unsupported modes, no-network public parameters, authorized Env and individual references, rotation/deletion, redaction and SDK handoff. Historical September 10 compact/medium/expanded UI evidence is retained; no fresh browser, live inference, provider account, generated-app execution or release was performed.

package/docs/airtable.md

@@ -0,0 +1,130 @@
+# Airtable
+
+Import `airtableProvider` from `@jskit-ai/connectors-catalog/server/airtable`.
+The initial adapter uses a personal access token (PAT), recorded as the common
+`api-key` authentication method. OAuth installation is not implemented by this
+adapter yet. Legacy account API keys cannot authenticate.
+
+## Set up access
+
+1. Sign in as the account that should own the connection. Open
+   [Developer hub](https://airtable.com/create/tokens).
+2. Choose **Personal access tokens**, then **Create token**. Name it for the
+   application/environment.
+3. Choose **Add a scope**. Add `schema.bases:read` for discovery,
+   `data.records:read` for reading records, `data.records:write` for creating,
+   updating or deleting records, and `schema.bases:write` only when the app
+   creates bases or changes tables/fields. Base creation needs Workspace Creator access and a token resource grant covering the target workspace. The token owner needs Editor access for record writes
+   and Creator access for schema writes; scopes do not increase base permissions.
+4. Under access, select the individual bases or workspaces the app needs.
+   A token only inherits rights the creating account already has.
+5. Create the token. Store the value outside source, for example in the backend
+   environment as `AIRTABLE_TOKEN`. In `integrations.json`, set provider
+   `airtable`, account mode `shared` or `assistant`, empty `scopes`, and
+   `authentication: { "method": "api-key", "secretRef": "env:AIRTABLE_TOKEN" }`.
+   Leave `registrations` empty for this slot.
+6. Use `connectApiKey` to verify access. Rotating the value behind the same
+   reference affects the next operation; changing the reference requires
+   verification again. See [Airtable's PAT guide](https://support.airtable.com/docs/creating-personal-access-tokens).
+
+## Runtime and AI composition
+
+`bases.list` calls `GET /v0/meta/bases`. Its optional `offset` is the cursor
+returned by the previous page. Results retain `bases` and `offset`. There is no
+page-size input: this endpoint pages up to 1,000 bases. An empty collection
+can indicate missing resource grants or an organization restriction; it does
+not prove access to a particular base. See [List bases](https://airtable.com/developers/web/api/list-bases).
+
+Use the [API-key source pattern](../patterns/api-key-connection/PATTERN.md),
+substituting this provider, slot and secret reference. The application owns
+authorization and maps the trusted caller to the connection owner. The library
+supplies validation, HTTP errors and file persistence. A CLI and Vibe64 edit
+the same JSON. The provider supplies the record and schema operations below. Application screens
+and rules deciding which rows a caller may access remain application work.
+
+## Provisioning automation and capacity
+
+An AI can prepare configuration, secret names and operation calls once a PAT
+is supplied. No supported ordinary-account API for issuing PATs was verified
+in this pass; token creation and resource grants use the console above.
+The application owner supplies its authorized PAT through private Env. Two
+PAT names alone do not establish separate capacity:
+check the relevant base, workspace and token-owner limits. OAuth registrations
+for distribution to unrelated customers are a separate future mode.
+
+Automated fixtures verify the authenticated endpoint, encoded pagination,
+file-store restart, rotation, isolation, disconnect, malformed success and
+401/403/429 failures. No real Airtable account was used.
+
+## Record and schema workflows
+
+`bases.create` accepts `{ name, workspaceId, tables }`. Supply an explicitly
+selected Airtable workspace ID and at least one table containing at least one
+field; field names must be unique ignoring case. This writes a new base and must
+be an explicitly authorized action, never part of verification. The first field
+is the primary field. A token granted only one existing base cannot provision
+another base: grant the intended workspace in the PAT's resource access and use
+an account with Workspace Creator access. The API returns the new base ID and
+table schema. Existing-base workflows need no workspace ID.
+[Create base](https://airtable.com/developers/web/api/create-base).
+
+
+Use `tables.list` with `{ baseId }` to discover the base's tables and fields.
+Prefer returned table and field IDs over mutable display names. A selected token
+resource grant is still required even when the API scope is enabled.
+[Base schema](https://airtable.com/developers/web/api/get-base-schema).
+
+```js
+const page = await connections.invoke({ context, integrationId: "data",
+  operation: "records.list", input: { baseId: "appYourBase", tableId: "tblYourTable",
+    pageSize: 100, filterByFormula: '{Status}="Open"' } });
+const created = await connections.invoke({ context, integrationId: "data",
+  operation: "records.create", input: { baseId: "appYourBase", tableId: "tblYourTable",
+    fields: { Name: "A task", Done: false } } });
+await connections.invoke({ context, integrationId: "data", operation: "records.update",
+  input: { baseId: "appYourBase", tableId: "tblYourTable", recordId: created.id,
+    fields: { Done: true } } });
+```
+
+`records.list` uses the documented POST `/listRecords` variant, avoiding URL
+length limits for formulas. Supply returned `offset` on the next call and retain
+the same view/formula. No offset means the last page. Inputs include optional
+`view` and `filterByFormula`, and `pageSize` from 1 to 100. Empty values may be
+omitted by Airtable; absence in a read response does not mean a field was removed.
+[Record listing](https://airtable.com/developers/web/api/list-records).
+
+`records.create` creates one record. `records.update` uses PATCH, preserving
+unspecified cells. Both require a nonempty `fields` object and disable automatic
+`typecast`. Validate user fields against your application contract and the returned
+Airtable schema; the API validates provider-specific cell formats. Do not copy
+arbitrary HTTP request bodies into this operation. Use `records.delete` with
+`{ baseId, tableId, recordId }` for an explicitly authorized deletion. None of
+these mutations occurs on connection verification.
+[Create](https://airtable.com/developers/web/api/create-records),
+[update](https://airtable.com/developers/web/api/update-record),
+[delete](https://airtable.com/developers/web/api/delete-record).
+
+`tables.create` accepts `{ baseId, name, description?, fields }`, where each field
+has `name`, `type`, and optional `description`/`options`. The first field is the
+primary field; choose a supported primary type such as `singleLineText` and unique
+field names. `tables.update` accepts `{ baseId, tableId, name, description? }`.
+`fields.create` accepts `{ baseId, tableId, field }`; `fields.update` accepts
+`{ baseId, tableId, fieldId, name, description?, options? }`. Use the documented
+write shape for each field type, not a copied read-only schema response. Unknown
+field types/options are rejected by Airtable, not converted silently. The adapter
+currently requires a name on schema updates.
+[Create table](https://airtable.com/developers/web/api/create-table),
+[update table](https://airtable.com/developers/web/api/update-table),
+[create field](https://airtable.com/developers/web/api/create-field),
+[update field](https://airtable.com/developers/web/api/update-field).
+
+Surface 403 as missing scope, base resource, account role or policy; surface 429
+for application-owned backoff. Uncertain writes are not automatically retried.
+The application owns deduplication/reconciliation before another creation attempt.
+
+`test/airtable.test.js` proves the schema and record workflow through the real
+connection service with controlled responses: discovery, table/field writes,
+pagination, encoded table names, partial updates, deletion, nonempty field
+validation, authorization, app isolation, 403/429 and uncertain-write handling.
+One focused test passed. No live Airtable account was used. This is runtime
+repair evidence. A focused public-editor browser fixture also passed: PAT references save without secrets, and scope, verification and revocation guidance is visible. This adapter does not itself attach tools to an editor’s coding assistant; that remains an assistant-host responsibility.