@jskit-ai/connectors-catalog 0.1.62 → 0.1.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/connectors-catalog",
-  "version": "0.1.62",
+  "version": "0.1.63",
   "description": "Provider definitions and focused API operations for JSKIT connectors.",
   "type": "module",
   "exports": {
@@ -123,14 +123,14 @@
     "@aws-sdk/client-redshift-data": "3.1128.0",
     "@aws-sdk/client-s3": "3.1128.0",
     "@aws-sdk/s3-request-presigner": "3.1128.0",
-    "@jskit-ai/connectors-core": "0.1.61",
+    "@jskit-ai/connectors-core": "0.1.62",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@smithy/fetch-http-handler": "5.8.0",
     "jose": "^6.1.3",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.244"
+    "@jskit-ai/kernel": "0.1.245"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/oauth-connection/PATTERN.md

@@ -181,6 +181,31 @@ comma-separated permissions. Oura handles reduced callback scopes and rotated
 refresh tokens. Some providers do not return a refresh token; expired access
 then needs consent again. Provider PKCE enforcement needs provider evidence.
 
+## Shared connection from an Env refresh token
+
+When the application's host already holds a long-lived grant for the shared
+account (the owner connected it once with the same OAuth client), skip consent
+in the app: add `refreshTokenRef` to a `shared` oauth2 integration whose
+registration uses the authorization-code flow.
+
+```json
+"authentication": {
+  "method": "oauth2",
+  "registrationRef": "google",
+  "refreshTokenRef": "env:GOOGLE_REFRESH_TOKEN"
+}
+```
+
+The Env value is a seed. On first use, and whenever the value or the OAuth
+client changes, the runtime replaces the shared connection with one built from
+that refresh token. From then on it refreshes and stores rotated tokens in the
+application's own store as usual. `status()` reports `source: "env"` (show it as
+"Connected from Env"). `beginAuthorization()` and `disconnect()` refuse with
+`connector_env_managed`: "This connection comes from an Env value; unlink or
+replace that value instead." A revoked token fails with "The refresh token in
+Env no longer works; replace that Env value." The refresh token must come from
+the same client as `registrationRef`; non-JSKIT apps read the variable directly.
+
 ## Twitch composition
 
 Use `twitchProvider` from `@jskit-ai/connectors-catalog/server/twitch` in the

package/src/shared/algolia.js

@@ -12,7 +12,7 @@ const algoliaDefinition = Object.freeze({
   settingsFields: [
     { name: "applicationId", label: "Application ID", hint: "Copy the ID from your Algolia application's API Keys page. This ID can be public." },
     { name: "publicApiKeyRef", environmentCredential: { label: "Public frontend API key", public: true }, label: "Public API key reference (optional)", placeholder: "env:ALGOLIA_SEARCH_KEY",
-      hint: "Optional search-only key for your frontend. Enter its reference; your app decides whether to publish its value." }
+      hint: "Optional search-only key for your frontend. Enter its reference; your app decides whether to expose its value." }
   ],
   setup: {
     url: "https://www.algolia.com/doc/guides/security/api-keys",
@@ -22,7 +22,7 @@ const algoliaDefinition = Object.freeze({
       "Copy the new backend key. Enter env:ALGOLIA_API_KEY in API key reference here and save. Choose Set credential in Env for ALGOLIA_API_KEY, paste its value and save it there.",
       "If the frontend will search Algolia directly, create a separate key with Search (search) access restricted to indices safe for those users to read. Enter env:ALGOLIA_SEARCH_KEY in Public API key reference (optional), save, then use its Set credential in Env link to store that key value.",
       "Return here and choose Connect account (or Verify again for an existing connection). Check connection only reads the application’s saved status. No OAuth registration or callback URL is needed. Verification lists indices with the backend key; it does not validate the optional frontend key.",
-      "If access fails, check the Application ID, selected indices, permissions and key expiry. Your framework owns publishing the optional frontend key; keep the backend key server-side."
+      "If access fails, check the Application ID, selected indices, permissions and key expiry. Your framework owns exposing the optional frontend key; keep the backend key server-side."
     ]
   }
 });

package/src/shared/firebase-cloud-messaging.js

@@ -26,7 +26,7 @@ const firebaseCloudMessagingDefinition = Object.freeze({
     { name: "projectId", label: "Firebase project ID", placeholder: "my-notifications-app", hint: "The project receiving messages. Usually project_id in your JSON; cross-project access requires an IAM grant on this target project." },
     { name: "clientMode", label: "Client setup", items: [{ value: "server", title: "Server or native only" }, { value: "web", title: "Include web push" }],
       hint: "Existing mobile/browser targets need server credentials. Include web push to configure browser registration too." },
-    { name: "apiKey", label: "Firebase API key", placeholder: "AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", hint: "Public API key from the Firebase web app configuration. This value is visible in your published app." },
+    { name: "apiKey", label: "Firebase API key", placeholder: "AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", hint: "Public API key from the Firebase web app configuration. This value is visible in your deployed app." },
     { name: "appId", label: "Firebase App ID", placeholder: "1:123456789012:web:abcdef1234567890", hint: "Public appId from the same Firebase project and web app." },
     { name: "vapidKey", label: "Web Push VAPID key", placeholder: "BEl62...", hint: "Public key from Project settings > Cloud Messaging > Web Push certificates. Never paste the private VAPID key." }
   ],

package/src/shared/google-maps-platform.js

@@ -18,7 +18,7 @@ const googleMapsPlatformDefinition = Object.freeze({
       "Restrict the server key to Geocoding API and the backend's outbound IPs. Enter env:GOOGLE_MAPS_SERVER_KEY in Server API key reference, Save configuration, then Set credential in Env. Save the real key as GOOGLE_MAPS_SERVER_KEY.",
       "For places and routes, also enable Places API (New) and Routes API in Library, then add them to the server key API restrictions. Place names/address/location use billable data fields; set quotas and review current pricing. Geocoding verification does not test these additional APIs.",
       "For browser maps, enable Maps JavaScript API. Open Google Maps Platform > Map management > Create map ID, select JavaScript and copy the ID into Map ID. The app loads Google's SDK with its separate browser key and gives the map container a height. Advanced markers require a map ID.",
-      "For browser maps, create a separate key restricted to the required browser APIs and Websites, including the actual preview and custom domains. Enter env:GOOGLE_MAPS_BROWSER_KEY in Browser API key reference and save that value separately in Env. The app publishes this browser key; never publish the server key.",
+      "For browser maps, create a separate key restricted to the required browser APIs and Websites, including the actual preview and custom domains. Enter env:GOOGLE_MAPS_BROWSER_KEY in Browser API key reference and save that value separately in Env. The app exposes this browser key; never expose the server key.",
       "Save configuration, enter Verification address, then Connect account. This performs one potentially billable geocoding request. It verifies only the server key, not browser maps. No OAuth registration or callback is needed.",
       "Update Env when replacing a key. Disconnect removes local connection state; delete or restrict the key in Google Cloud to revoke provider access. Check existing usage before deleting a key used by other applications."
     ]

package/src/shared/google.js

@@ -84,7 +84,7 @@ const googleSearchConsoleDefinition = definition("google-search-console", "Googl
   "The connecting Google account needs access to the intended Search Console property. A property owner can open that property, choose Settings > Users and permissions > Add user, enter the account email, choose the appropriate role and save.",
   "To add a property, open Search Console > property selector > Add property. Domain properties require your DNS provider's TXT record; URL-prefix properties offer verification methods such as an HTML file or tag. Follow Google's displayed instructions and Verify, or have an existing owner add this account. An OAuth grant does not verify domain ownership.",
   "Search performance uses finalized Pacific-time dates and top rows, not a complete traffic export. URL inspection reports Google's indexed snapshot, not a live page test or request for indexing. Use the exact property identifier returned by the connection.",
-  "To submit or remove sitemaps, select Manage Search Console properties (webmasters), add the scope in Data Access and reconnect. The app must publish a real sitemap URL first. Submission does not create the file, guarantee indexing or change DNS; deletion removes its Search Console entry, not the hosted file.",
+  "To submit or remove sitemaps, select Manage Search Console properties (webmasters), add the scope in Data Access and reconnect. The app must serve a real sitemap URL first. Submission does not create the file, guarantee indexing or change DNS; deletion removes its Search Console entry, not the hosted file.",
   "Keep Read Search Console properties for the initial check, which lists accessible properties. Site Verification permissions alone do not authorize that check or create property access. An empty result can mean this Google account has no properties."
 ]);
 const googleAnalyticsDefinition = Object.freeze({
@@ -98,7 +98,7 @@ const googleAnalyticsDefinition = Object.freeze({
     validator: (value) => /^G-[A-Z0-9]+$/u.test(value) || "Enter the GA4 web stream Measurement ID beginning G-."
   } }),
   settingsFields: [{ name: "measurementId", label: "Measurement ID", required: true,
-    hint: "Public: this value will be visible in your published application. Copy it from your GA4 web stream." }],
+    hint: "Public: this value will be visible in your deployed application. Copy it from your GA4 web stream." }],
   setup: {
     url: "https://support.google.com/analytics/answer/9304153",
     steps: [

package/src/shared/logo-dev.js

@@ -3,11 +3,11 @@ const logoDevDefinition = Object.freeze({
   accountModes: ["shared", "assistant"], authenticationMethods: ["api-key"], scopes: [],
   runtimeKind: "public-resource", configurationOnly: true,
   apiKeyReferenceLabel: "Publishable key reference",
-  apiKeyReferenceHint: "Reference a pk_ key. Your application publishes its value in image URLs. A private sk_ key cannot be used for this image flow.",
+  apiKeyReferenceHint: "Reference a pk_ key. Your application exposes its value in image URLs. A private sk_ key cannot be used for this image flow.",
   setup: {
     url: "https://www.logo.dev/docs/platform/api-keys",
     steps: [
-      "Sign into https://www.logo.dev/dashboard/api-keys and copy the publishable key beginning pk_. Do not copy the private sk_ key: this integration displays images, and its pk_ value will be visible in the published application's image URLs.",
+      "Sign into https://www.logo.dev/dashboard/api-keys and copy the publishable key beginning pk_. Do not copy the private sk_ key: this integration displays images, and its pk_ value will be visible in the deployed application's image URLs.",
       "Enter env:LOGO_DEV_PUBLISHABLE_KEY in Publishable key reference, then Save configuration. Choose Set credential in Env and store the actual pk_ value as LOGO_DEV_PUBLISHABLE_KEY. Return after saving Env. Your application must resolve this reference and expose only this publishable value to its image code.",
       "In Logo.dev API Keys, enable Allowed Domains Only, enter allowed domains one per line, then Save Changes. Include the application's actual hosting/custom domain and intended preview domains. example.com matches that domain; *.example.com matches its subdomains. Add localhost explicitly if needed for local development.",
       "Before enabling restrictions, ensure image requests send an origin referrer. Use referrerpolicy=origin on the image or an equivalent application policy; no-referrer and same-origin policies block cross-site referrers. Unlisted domains or missing referrers cause image failures.",

package/src/shared/mapbox.js

@@ -14,7 +14,7 @@ const mapboxDefinition = Object.freeze({
   }),
   settingsFields: [{ name: "usage", label: "Mapbox usage", credentialScope: value => value,
     items: [{ title: "Backend geocoding and optional browser maps", value: "backend" }, { title: "Browser maps only", value: "browser" }] }, { name: "publicTokenRef", environmentCredential: { label: "Public browser token", public: true }, label: "Public browser token reference", placeholder: "env:MAPBOX_PUBLIC_TOKEN",
-    hint: "Required for browser-only mode; optional with backend geocoding. Separate pk. token for Mapbox in your browser. The application may publish this value; backend verification does not verify its restrictions." }],
+    hint: "Required for browser-only mode; optional with backend geocoding. Separate pk. token for Mapbox in your browser. The application may expose this value; backend verification does not verify its restrictions." }],
   setup: {
     url: "https://docs.mapbox.com/accounts/guides/tokens/",
     stepsForSettings(settings) { return settings?.usage === "browser" ? [
@@ -26,7 +26,7 @@ const mapboxDefinition = Object.freeze({
     ] : this.steps; },
     steps: [
       "Sign into Mapbox Developer Console → Access Tokens → Create a token. Name it for this application and environment. Select only the scopes your APIs need; geocoding can use a public pk. token. Copy a secret sk. token immediately: it is shown only once.",
-      "For backend geocoding, enter env:MAPBOX_BACKEND_TOKEN in Backend access token reference. Use a token without browser URL restrictions: backend requests have no browser referrer. Never publish a secret sk. token in browser code.",
+      "For backend geocoding, enter env:MAPBOX_BACKEND_TOKEN in Backend access token reference. Use a token without browser URL restrictions: backend requests have no browser referrer. Never expose a secret sk. token in browser code.",
       "For browser maps, create a separate public pk. token with the SDK’s map scopes, including styles:read and fonts:read. Enter env:MAPBOX_PUBLIC_TOKEN in Public browser token reference. The application must deliberately load this public value; this connector does not render a map.",
       "Restrict the browser token to the deployed application URLs, adding preview, custom domains and localhost when needed. Create a new token rather than using the default public token, which cannot be URL-restricted. Wildcards are unsupported; blocking the Referer header can cause 403 errors.",
       "Save configuration, then use Set credential in Env for MAPBOX_BACKEND_TOKEN and Open Env for MAPBOX_PUBLIC_TOKEN if supplied. Store token values there, not in reference fields. Connect account verifies only the backend token’s validity; it does not test geocoding entitlement or the optional browser token. No OAuth app or callback URL is needed.",

package/src/shared/tokens.js

@@ -655,7 +655,7 @@ const lexwareDefinition = definition("lexware", "Lexware", "Read accounting cont
     "Draft invoices require an existing contact UUID, invoice and service/delivery dates with timezones, and custom lines with quantity, unit, net EUR amount and tax rate. Choose those accounting values in the app; the connector does not infer tax. Review and finalize drafts in Lexware. No email or payment is sent.",
     "An interrupted invoice creation may already have succeeded. Check the voucher list before repeating it. Respect the provider limit of two requests per second across endpoints. The app must authorize each contact/document and approve writes before calling the connector.",
     "This adapter does not create contacts/articles/vouchers, download PDFs, finalize invoices, upload receipts or receive accounting events. For example, it can prepare a draft booking invoice for an existing customer, but receipt intake and signed event processing need native app implementation.",
-    "No OAuth registration or callback URL is needed. Verification reads contacts. Keys expire after at most 24 months: create a replacement and update Env before expiry. Public API does not mean the key is safe to publish."
+    "No OAuth registration or callback URL is needed. Verification reads contacts. Keys expire after at most 24 months: create a replacement and update Env before expiry. Public API does not mean the key is safe to expose."
   ]);
 const sevdeskDefinition = Object.freeze({
   ...definition("sevdesk", "Sevdesk", "Read sevdesk contact organizations and people with offset pagination.",
@@ -683,7 +683,7 @@ const attentionDefinition = definition("attention", "Attention", "Read conversat
     "Sign into app.attention.tech as an organization administrator. Open your profile avatar at the top left, Settings, then Organization > API Keys.",
     "Choose + Create API Key at the top right and give it a name identifying this application. Copy the value in API Key Created before closing; it is shown once.",
     "Enter env:ATTENTION_API_KEY in API key reference here and save. Choose Set credential in Env, paste the key as the ATTENTION_API_KEY value and save it there. Return here and choose Connect account (or Verify again when already connected). Check connection only reloads status.",
-    "An organization key can expose broad read/write and user-management access. Your application must restrict each operation to authorized users; never publish this key in frontend code. New users require an explicit listener or recording seat choice; check your Attention plan before enabling provisioning.",
+    "An organization key can expose broad read/write and user-management access. Your application must restrict each operation to authorized users; never expose this key in frontend code. New users require an explicit listener or recording seat choice; check your Attention plan before enabling provisioning.",
     "No OAuth registration or callback URL is needed. Verification reads a conversation page without changing recordings or CRM data.",
     "To replace access, create a new key and update Env, then verify before opening the old key's three-dot menu and choosing Delete. Deletion immediately stops every application still using that old key. Disconnect here removes the local grant only; revoke the key in Attention to stop provider access."
   ]);