@pylonsync/functions 0.22.28 → 0.22.30

package/dist/types.d.ts

@@ -746,29 +746,35 @@ export interface LlmCompleteResponse {
     };
 }
 /**
- * Server-side OAuth connection registry. Apps declare connections
- * via `defineConnection({...})` in `app.ts`; this surface lets
- * actions fetch fresh access tokens (auto-refresh) and start the
- * OAuth dance.
+ * Server-side connection registry. Apps declare connections via
+ * `defineConnection({...})` in `app.ts`; this surface fetches fresh
+ * access tokens (auto-refresh), starts OAuth flows, and stores API keys.
  *
  * Available on mutation + action ctx only — connections perform
  * external I/O (token refresh, DB writes) that doesn't belong
  * inside a reactive query.
  *
- * All ops require an authenticated caller (`ctx.auth.userId !==
- * null`). Public functions must `ctx.auth.elevate({ admin: true,
- * reason: "..." })` before reaching `ctx.connections.*`.
+ * Who may do what:
+ * - `owner: "user"` (default): the signed-in caller's own connection.
+ *   Every op needs a signed-in, non-guest caller.
+ * - `owner: "app"`: one connection for the whole app. `get` works for
+ *   any caller, including an anonymous visitor's request, so the
+ *   function decides what the caller may do with it. `authorizeUrl`,
+ *   `setCredentials`, and `disconnect` need an admin
+ *   (`ctx.auth.elevate({ admin: true, reason })`).
  */
 export interface Connections {
     /**
-     * Mint the URL the browser should navigate to so the user can
-     * link an external account. `name` matches a `defineConnection({...})`
-     * entry. `postRedirect` (optional) is where the browser lands
-     * after a successful callback — defaults to `/`.
+     * Mint the URL the browser should navigate to so the account can be
+     * linked. `name` matches an OAuth `defineConnection({...})` entry.
+     * `postRedirect` (optional, a relative path) is where the browser
+     * lands after a successful callback — defaults to `/`.
      *
      * Throws `CONNECTIONS_NOT_CONFIGURED`, `CONNECTION_UNKNOWN`,
-     * `PROVIDER_NOT_CONFIGURED`, or `ENCRYPTION_REQUIRED` (refresh
-     * tokens are not allowed to land in plaintext).
+     * `CONNECTION_FORBIDDEN`, `CONNECTION_WRONG_KIND`,
+     * `CONNECTION_MANAGED` (the hosting platform runs this app
+     * connection's flow), `PROVIDER_NOT_CONFIGURED`, or
+     * `ENCRYPTION_REQUIRED` (tokens are not allowed to land in plaintext).
      */
     authorizeUrl(name: string, opts?: {
         postRedirect?: string;
@@ -776,31 +782,54 @@ export interface Connections {
         url: string;
     }>;
     /**
-     * Returns a fresh access token for `(ctx.auth.userId, name)`. If
-     * the stored token expires within 60s, the framework refreshes
-     * via the provider's refresh-token grant FIRST, persists the new
-     * token pair, then returns the new access token.
+     * Returns a fresh access token. If the stored token expires within
+     * 60s, the framework refreshes it first (through the hosting
+     * platform for a brokered app connection), persists the new pair,
+     * then returns it. For an API-key connection `accessToken` is the
+     * first key field and `credentials` holds every field.
      *
-     * Throws `CONNECTION_NOT_LINKED` when the user hasn't started
-     * the OAuth flow, `REFRESH_FAILED` when the provider rejects
-     * the refresh token (user must re-link).
+     * `accountId` is the provider's id for the connected account
+     * (Square merchant, Stripe account, Clover merchant). `metadata`
+     * holds non-secret provider data (Mailchimp's `dc`).
+     *
+     * Throws `CONNECTION_NOT_LINKED` when nothing is connected yet,
+     * `REFRESH_FAILED` when the provider rejects the refresh token (the
+     * account must be linked again).
      */
     get(name: string): Promise<{
         accessToken: string;
         scope: string | null;
         expiresAt: number | null;
+        accountId: string | null;
+        metadata: Record<string, unknown> | null;
+        credentials: Record<string, string> | null;
     }>;
-    /** List the signed-in user's linked connections. Token values
-     *  are NOT included — call `get(name)` for those. */
+    /** The linked connections the caller can see: their own and the
+     *  app's. Token values are NOT included — call `get(name)`. */
     list(): Promise<{
         connections: Array<{
             name: string;
             provider: string;
+            owner: "user" | "app";
+            kind: "oauth" | "api_key";
+            accountId: string | null;
             scope: string | null;
             expiresAt: number | null;
             updatedAt: number;
         }>;
     }>;
+    /**
+     * Store an API-key connection. `credentials` must have exactly the
+     * connection's fields. For a known provider (`stripe`, `square`,
+     * `toast`) the provider is called first to confirm the key works.
+     *
+     * Throws `CONNECTION_WRONG_KIND`, `INVALID_CREDENTIALS`, or
+     * `CREDENTIAL_CHECK_FAILED`.
+     */
+    setCredentials(name: string, credentials: Record<string, string>): Promise<{
+        connected: boolean;
+        accountId: string | null;
+    }>;
     /** Remove the stored connection. Provider-side revocation is
      *  the caller's responsibility — most providers expose a separate
      *  `/revoke` endpoint that this surface intentionally doesn't

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.22.28",
+  "version": "0.22.30",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime.ts

@@ -1174,11 +1174,21 @@ function buildConnections(callId: string): Connections {
         type: "connection",
         op: "get",
         payload: { name },
-      })) as { access_token: string; scope: string | null; expires_at: number | null };
+      })) as {
+        access_token: string;
+        scope: string | null;
+        expires_at: number | null;
+        account_id: string | null;
+        metadata: Record<string, unknown> | null;
+        credentials: Record<string, string> | null;
+      };
       return {
         accessToken: data.access_token,
         scope: data.scope,
         expiresAt: data.expires_at,
+        accountId: data.account_id ?? null,
+        metadata: data.metadata ?? null,
+        credentials: data.credentials ?? null,
       };
     },
     async list() {
@@ -1190,21 +1200,39 @@ function buildConnections(callId: string): Connections {
         connections: Array<{
           name: string;
           provider: string;
+          owner: "user" | "app";
+          kind: "oauth" | "api_key";
+          connected: boolean;
+          account_id: string | null;
           scope: string | null;
           expires_at: number | null;
-          updated_at: number;
+          updated_at: number | null;
         }>;
       };
+      // Linked connections only, as before app connections existed.
       return {
-        connections: data.connections.map((c) => ({
-          name: c.name,
-          provider: c.provider,
-          scope: c.scope,
-          expiresAt: c.expires_at,
-          updatedAt: c.updated_at,
-        })),
+        connections: data.connections
+          .filter((c) => c.connected)
+          .map((c) => ({
+            name: c.name,
+            provider: c.provider,
+            owner: c.owner,
+            kind: c.kind,
+            accountId: c.account_id,
+            scope: c.scope,
+            expiresAt: c.expires_at,
+            updatedAt: c.updated_at ?? 0,
+          })),
       };
     },
+    async setCredentials(name, credentials) {
+      const data = (await rpc(callId, {
+        type: "connection",
+        op: "set_credentials",
+        payload: { name, credentials },
+      })) as { connected: boolean; account_id: string | null };
+      return { connected: data.connected, accountId: data.account_id ?? null };
+    },
     async disconnect(name) {
       return (await rpc(callId, {
         type: "connection",

package/src/types.ts

@@ -840,29 +840,35 @@ export interface LlmCompleteResponse {
 // ---------------------------------------------------------------------------
 
 /**
- * Server-side OAuth connection registry. Apps declare connections
- * via `defineConnection({...})` in `app.ts`; this surface lets
- * actions fetch fresh access tokens (auto-refresh) and start the
- * OAuth dance.
+ * Server-side connection registry. Apps declare connections via
+ * `defineConnection({...})` in `app.ts`; this surface fetches fresh
+ * access tokens (auto-refresh), starts OAuth flows, and stores API keys.
  *
  * Available on mutation + action ctx only — connections perform
  * external I/O (token refresh, DB writes) that doesn't belong
  * inside a reactive query.
  *
- * All ops require an authenticated caller (`ctx.auth.userId !==
- * null`). Public functions must `ctx.auth.elevate({ admin: true,
- * reason: "..." })` before reaching `ctx.connections.*`.
+ * Who may do what:
+ * - `owner: "user"` (default): the signed-in caller's own connection.
+ *   Every op needs a signed-in, non-guest caller.
+ * - `owner: "app"`: one connection for the whole app. `get` works for
+ *   any caller, including an anonymous visitor's request, so the
+ *   function decides what the caller may do with it. `authorizeUrl`,
+ *   `setCredentials`, and `disconnect` need an admin
+ *   (`ctx.auth.elevate({ admin: true, reason })`).
  */
 export interface Connections {
   /**
-   * Mint the URL the browser should navigate to so the user can
-   * link an external account. `name` matches a `defineConnection({...})`
-   * entry. `postRedirect` (optional) is where the browser lands
-   * after a successful callback — defaults to `/`.
+   * Mint the URL the browser should navigate to so the account can be
+   * linked. `name` matches an OAuth `defineConnection({...})` entry.
+   * `postRedirect` (optional, a relative path) is where the browser
+   * lands after a successful callback — defaults to `/`.
    *
    * Throws `CONNECTIONS_NOT_CONFIGURED`, `CONNECTION_UNKNOWN`,
-   * `PROVIDER_NOT_CONFIGURED`, or `ENCRYPTION_REQUIRED` (refresh
-   * tokens are not allowed to land in plaintext).
+   * `CONNECTION_FORBIDDEN`, `CONNECTION_WRONG_KIND`,
+   * `CONNECTION_MANAGED` (the hosting platform runs this app
+   * connection's flow), `PROVIDER_NOT_CONFIGURED`, or
+   * `ENCRYPTION_REQUIRED` (tokens are not allowed to land in plaintext).
    */
   authorizeUrl(
     name: string,
@@ -870,33 +876,57 @@ export interface Connections {
   ): Promise<{ url: string }>;
 
   /**
-   * Returns a fresh access token for `(ctx.auth.userId, name)`. If
-   * the stored token expires within 60s, the framework refreshes
-   * via the provider's refresh-token grant FIRST, persists the new
-   * token pair, then returns the new access token.
+   * Returns a fresh access token. If the stored token expires within
+   * 60s, the framework refreshes it first (through the hosting
+   * platform for a brokered app connection), persists the new pair,
+   * then returns it. For an API-key connection `accessToken` is the
+   * first key field and `credentials` holds every field.
    *
-   * Throws `CONNECTION_NOT_LINKED` when the user hasn't started
-   * the OAuth flow, `REFRESH_FAILED` when the provider rejects
-   * the refresh token (user must re-link).
+   * `accountId` is the provider's id for the connected account
+   * (Square merchant, Stripe account, Clover merchant). `metadata`
+   * holds non-secret provider data (Mailchimp's `dc`).
+   *
+   * Throws `CONNECTION_NOT_LINKED` when nothing is connected yet,
+   * `REFRESH_FAILED` when the provider rejects the refresh token (the
+   * account must be linked again).
    */
   get(name: string): Promise<{
     accessToken: string;
     scope: string | null;
     expiresAt: number | null;
+    accountId: string | null;
+    metadata: Record<string, unknown> | null;
+    credentials: Record<string, string> | null;
   }>;
 
-  /** List the signed-in user's linked connections. Token values
-   *  are NOT included — call `get(name)` for those. */
+  /** The linked connections the caller can see: their own and the
+   *  app's. Token values are NOT included — call `get(name)`. */
   list(): Promise<{
     connections: Array<{
       name: string;
       provider: string;
+      owner: "user" | "app";
+      kind: "oauth" | "api_key";
+      accountId: string | null;
       scope: string | null;
       expiresAt: number | null;
       updatedAt: number;
     }>;
   }>;
 
+  /**
+   * Store an API-key connection. `credentials` must have exactly the
+   * connection's fields. For a known provider (`stripe`, `square`,
+   * `toast`) the provider is called first to confirm the key works.
+   *
+   * Throws `CONNECTION_WRONG_KIND`, `INVALID_CREDENTIALS`, or
+   * `CREDENTIAL_CHECK_FAILED`.
+   */
+  setCredentials(
+    name: string,
+    credentials: Record<string, string>
+  ): Promise<{ connected: boolean; accountId: string | null }>;
+
   /** Remove the stored connection. Provider-side revocation is
    *  the caller's responsibility — most providers expose a separate
    *  `/revoke` endpoint that this surface intentionally doesn't