zitejs 0.9.129 → 0.9.130

package/dist/cjs/integrations/client.d.ts

@@ -3,12 +3,14 @@ export declare const INTEGRATIONS_CLASS_NAME = "Connections";
 /**
  * `accessToken` is the service's primary credential (for Twilio the account SID).
  * Call `get` where the value is used: a token refreshed mid-run is what the next call returns.
+ * For a workspace connection that isn't connected, `get` throws a `ZiteError`
+ * whose `userFacingMessage` is safe to show visitors.
  */
 export type Connected<Extra = {}> = {
     status: "connected";
     accessToken: string;
 } & Extra;
-/** No account behind the entry, or its token could not be refreshed. `connectUrl` is where a person fixes that. */
+/** A per-user entry the signed-in user hasn't connected, or whose token expired: send them to `connectUrl`. */
 export type NeedsConnect = {
     status: "missing" | "expired";
     connectUrl: string;
@@ -19,7 +21,8 @@ export interface IntegrationsClient<ByName extends Record<string, unknown>> {
 }
 /**
  * `ByName` maps each entry name to its answer, e.g.
- * `{ crm: Connected<{ instanceUrl: string }> | NeedsConnect }`; `zitejs generate`
- * writes it per app into `.zite/integrations/index.ts`.
+ * `{ crm: Connected<{ instanceUrl: string }>; inbox: Connected | NeedsConnect }`
+ * (only per-user entries can need connecting); `zitejs generate` writes it per
+ * app into `.zite/integrations/index.ts`.
  */
 export declare function createIntegrationsClient<ByName extends Record<string, unknown>>(): IntegrationsClient<ByName>;

package/dist/cjs/integrations/client.js

@@ -3,14 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.INTEGRATIONS_CLASS_NAME = exports.INTEGRATIONS_SDK_INTEGRATION_ID = void 0;
 exports.createIntegrationsClient = createIntegrationsClient;
 const sdkCall_js_1 = require("../internal/sdkCall.js");
-// The worker and runner answer this call under its original name; renaming the
-// wire protocol would break every deployed bundle for no user-visible gain.
+// The platform id the worker answers `get` under, as `__pdf__` is for PDFs.
 exports.INTEGRATIONS_SDK_INTEGRATION_ID = "__connections__";
 exports.INTEGRATIONS_CLASS_NAME = "Connections";
 /**
  * `ByName` maps each entry name to its answer, e.g.
- * `{ crm: Connected<{ instanceUrl: string }> | NeedsConnect }`; `zitejs generate`
- * writes it per app into `.zite/integrations/index.ts`.
+ * `{ crm: Connected<{ instanceUrl: string }>; inbox: Connected | NeedsConnect }`
+ * (only per-user entries can need connecting); `zitejs generate` writes it per
+ * app into `.zite/integrations/index.ts`.
  */
 function createIntegrationsClient() {
     return {

package/dist/cjs/integrations/client.test-d.js

@@ -8,6 +8,7 @@ const index_js_2 = require("../index.js");
     const client = (0, client_js_1.createIntegrationsClient)();
     (0, vitest_1.it)("types each name's answer", () => {
         (0, vitest_1.expectTypeOf)(client.get("crm")).resolves.toEqualTypeOf();
+        (0, vitest_1.expectTypeOf)(client.get("inbox")).resolves.toEqualTypeOf();
     });
     (0, vitest_1.it)("rejects a name the app cannot see", () => {
         // @ts-expect-error not a visible entry
@@ -18,23 +19,21 @@ const index_js_2 = require("../index.js");
         const none = (0, client_js_1.createIntegrationsClient)();
         (0, vitest_1.expectTypeOf)().toEqualTypeOf();
     });
-    (0, vitest_1.it)("narrows to the connected fields on status", async () => {
-        const crm = await client.get("crm");
-        if (crm.status === "connected") {
-            (0, vitest_1.expectTypeOf)(crm.instanceUrl).toEqualTypeOf();
+    (0, vitest_1.it)("narrows a per-user entry to the connected fields on status", async () => {
+        const inbox = await client.get("inbox");
+        if (inbox.status === "connected") {
+            (0, vitest_1.expectTypeOf)(inbox.accessToken).toEqualTypeOf();
         }
         else {
-            (0, vitest_1.expectTypeOf)(crm.connectUrl).toEqualTypeOf();
+            (0, vitest_1.expectTypeOf)(inbox.connectUrl).toEqualTypeOf();
         }
     });
 });
 (0, vitest_1.describe)("the untyped zitejs/integrations client", () => {
     (0, vitest_1.it)("takes any name; only accessToken is certain", async () => {
         const entry = await index_js_1.integrations.get("anything");
-        if (entry.status === "connected") {
-            (0, vitest_1.expectTypeOf)(entry.accessToken).toEqualTypeOf();
-            (0, vitest_1.expectTypeOf)(entry.instanceUrl).toEqualTypeOf();
-        }
+        (0, vitest_1.expectTypeOf)(entry.accessToken).toEqualTypeOf();
+        (0, vitest_1.expectTypeOf)(entry.instanceUrl).toEqualTypeOf();
     });
 });
 (0, vitest_1.describe)("CREDENTIAL_FIELDS", () => {

package/dist/cjs/integrations/index.d.ts

@@ -1,3 +1,3 @@
-import { type Connected, type NeedsConnect } from "./client.js";
+import { type Connected } from "./client.js";
 export type { Connected, NeedsConnect } from "./client.js";
-export declare const integrations: import("./client.js").IntegrationsClient<Record<string, NeedsConnect | Connected<Partial<Record<string, string>>>>>;
+export declare const integrations: import("./client.js").IntegrationsClient<Record<string, Connected<Partial<Record<string, string>>>>>;

package/dist/cjs/integrations/rules.d.ts

@@ -61,9 +61,12 @@ export declare const isCredentialServiceType: (type: string) => type is Credenti
 export type GettableIntegration = {
     name: string;
     serviceType: CredentialServiceType;
+    /** Each signed-in user connects their own account, so `get` can answer that they haven't. */
+    perUser: boolean;
 };
 export type ConfigIntegrations = Readonly<Record<string, {
     type?: unknown;
+    connectionMode?: unknown;
 } | undefined>>;
 /**
  * The entries a source dir can name, by name: its own, then the workspace's under

package/dist/cjs/integrations/rules.js

@@ -105,8 +105,13 @@ const gettableIntegrations = (rootIntegrations, appIntegrations) => {
         if (typeof entry?.type !== "string")
             continue;
         const serviceType = (0, exports.normalizeIntegrationServiceType)(entry.type);
-        if ((0, exports.isCredentialServiceType)(serviceType))
-            visible.push({ name, serviceType });
+        if ((0, exports.isCredentialServiceType)(serviceType)) {
+            visible.push({
+                name,
+                serviceType,
+                perUser: entry.connectionMode === "app-user",
+            });
+        }
     }
     return visible.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 };

package/dist/cjs/integrations/rules.test.js

@@ -47,9 +47,9 @@ const index_js_1 = require("../index.js");
 (0, vitest_1.describe)("gettableIntegrations", () => {
     (0, vitest_1.it)("lists the app's entries, then the workspace's under untaken keys, by name", () => {
         (0, vitest_1.expect)((0, index_js_1.gettableIntegrations)({ crm: { type: "salesforce" }, team: { type: "slack" } }, { billing: { type: "stripe" }, team: { type: "microsoftTeams" } })).toEqual([
-            { name: "billing", serviceType: "stripe" },
-            { name: "crm", serviceType: "salesforce" },
-            { name: "team", serviceType: "microsoftTeams" },
+            { name: "billing", serviceType: "stripe", perUser: false },
+            { name: "crm", serviceType: "salesforce", perUser: false },
+            { name: "team", serviceType: "microsoftTeams", perUser: false },
         ]);
     });
     (0, vitest_1.it)("lets an app entry of a generated-client type shadow a workspace credential entry", () => {
@@ -70,7 +70,7 @@ const index_js_1 = require("../index.js");
     });
     (0, vitest_1.it)("normalizes legacy type spellings", () => {
         (0, vitest_1.expect)((0, index_js_1.gettableIntegrations)({ cal: { type: "google-calendar" } })).toEqual([
-            { name: "cal", serviceType: "googleCalendar" },
+            { name: "cal", serviceType: "googleCalendar", perUser: false },
         ]);
     });
     (0, vitest_1.it)("drops a type it does not know, as the runtime does", () => {
@@ -78,7 +78,16 @@ const index_js_1 = require("../index.js");
     });
     (0, vitest_1.it)("shadows by own keys only", () => {
         (0, vitest_1.expect)((0, index_js_1.gettableIntegrations)({ constructor: { type: "slack" } }, {})).toEqual([
-            { name: "constructor", serviceType: "slack" },
+            { name: "constructor", serviceType: "slack", perUser: false },
+        ]);
+    });
+    (0, vitest_1.it)("marks an entry each signed-in user connects for themselves", () => {
+        (0, vitest_1.expect)((0, index_js_1.gettableIntegrations)({
+            inbox: { type: "gmail", connectionMode: "app-user" },
+            support: { type: "gmail" },
+        })).toEqual([
+            { name: "inbox", serviceType: "gmail", perUser: true },
+            { name: "support", serviceType: "gmail", perUser: false },
         ]);
     });
     (0, vitest_1.it)("works with no configs", () => {

package/dist/cjs/sync/lib.js

@@ -1427,7 +1427,7 @@ function generateIntegrationsIndex(entries, opts) {
         ? ["export type IntegrationByName = {};"]
         : [
             "export type IntegrationByName = {",
-            ...sorted.map(({ name, serviceType }) => `  ${tsSingleQuoted(name)}: ${connectedTypeFor(serviceType)} | NeedsConnect;`),
+            ...sorted.map(({ name, serviceType, perUser }) => `  ${tsSingleQuoted(name)}: ${connectedTypeFor(serviceType)}${perUser ? " | NeedsConnect" : ""};`),
             "};",
         ];
     return [
@@ -1437,8 +1437,10 @@ function generateIntegrationsIndex(entries, opts) {
         "// Usage in endpoints (src/api/*.ts) and automations (src/index.ts):",
         "//   import { integrations } from 'zitejs/integrations';",
         "//",
-        "//   const crm = await integrations.get('<entry name>');",
-        "//   if (crm.status !== 'connected') { /* crm.connectUrl is where a person reconnects */ }",
+        "//   const { accessToken } = await integrations.get('<entry name>');",
+        "//",
+        "// A workspace connection that isn't connected throws a ZiteError. A per-user",
+        "// entry answers `missing`/`expired` with a connectUrl for the signed-in user.",
         "//",
         "// Call get where the value is used, not once at module scope: a token refreshed",
         "// mid-run is what the next call returns.",

package/dist/cjs/sync/lib.test.js

@@ -467,8 +467,9 @@ const duplicateIdentifierErrorsIn = (source) => {
     };
     (0, vitest_1.it)('emits the client typed by name', () => {
         (0, vitest_1.expect)((0, lib_js_1.generateIntegrationsIndex)([
-            { name: 'team', serviceType: 'slack' },
-            { name: 'crm', serviceType: 'salesforce' },
+            { name: 'team', serviceType: 'slack', perUser: false },
+            { name: 'crm', serviceType: 'salesforce', perUser: false },
+            { name: 'inbox', serviceType: 'gmail', perUser: true },
         ], { reexportAirtable: false })).toMatchInlineSnapshot(`
       "// Auto-generated by zitejs generate from zite.config.json. Do not edit manually.
       // zitejs/integrations — an integration's credentials by its zite.config.json entry name.
@@ -476,8 +477,10 @@ const duplicateIdentifierErrorsIn = (source) => {
       // Usage in endpoints (src/api/*.ts) and automations (src/index.ts):
       //   import { integrations } from 'zitejs/integrations';
       //
-      //   const crm = await integrations.get('<entry name>');
-      //   if (crm.status !== 'connected') { /* crm.connectUrl is where a person reconnects */ }
+      //   const { accessToken } = await integrations.get('<entry name>');
+      //
+      // A workspace connection that isn't connected throws a ZiteError. A per-user
+      // entry answers \`missing\`/\`expired\` with a connectUrl for the signed-in user.
       //
       // Call get where the value is used, not once at module scope: a token refreshed
       // mid-run is what the next call returns.
@@ -487,11 +490,12 @@ const duplicateIdentifierErrorsIn = (source) => {
 
       export type { Connected, NeedsConnect };
 
-      export type IntegrationName = 'crm' | 'team';
+      export type IntegrationName = 'crm' | 'inbox' | 'team';
 
       export type IntegrationByName = {
-        'crm': Connected<{ instanceUrl: string }> | NeedsConnect;
-        'team': Connected | NeedsConnect;
+        'crm': Connected<{ instanceUrl: string }>;
+        'inbox': Connected | NeedsConnect;
+        'team': Connected;
       };
 
       export const integrations = createIntegrationsClient<IntegrationByName>();
@@ -500,33 +504,34 @@ const duplicateIdentifierErrorsIn = (source) => {
     });
     // The platform leaves these out for some accounts, so the type can't promise them.
     (0, vitest_1.it)('marks an extra the platform may omit as optional', () => {
-        const generated = (0, lib_js_1.generateIntegrationsIndex)([{ name: 'tickets', serviceType: 'jira' }], { reexportAirtable: false });
-        (0, vitest_1.expect)(generated).toContain("'tickets': Connected<{ cloudId: string; siteUrl?: string }> | NeedsConnect;");
+        const generated = (0, lib_js_1.generateIntegrationsIndex)([{ name: 'tickets', serviceType: 'jira', perUser: false }], { reexportAirtable: false });
+        (0, vitest_1.expect)(generated).toContain("'tickets': Connected<{ cloudId: string; siteUrl?: string }>;");
         (0, vitest_1.expect)(typeErrorsIn(generated, `import { integrations } from 'zitejs/integrations';
 const jira = await integrations.get('tickets');
-if (jira.status === 'connected') {
-  const cloudId: string = jira.cloudId;
-  const siteUrl: string = jira.siteUrl;
-}
+const cloudId: string = jira.cloudId;
+const siteUrl: string = jira.siteUrl;
 `)).toEqual([
             vitest_1.expect.stringContaining("Type 'string | undefined' is not assignable"),
         ]);
     });
+    // A workspace entry is used as is; only a per-user one makes code check first.
     (0, vitest_1.it)('types get per name in app code', () => {
         const generated = (0, lib_js_1.generateIntegrationsIndex)([
-            { name: 'crm', serviceType: 'salesforce' },
-            { name: 'warehouse', serviceType: 'clickhouse' },
+            { name: 'crm', serviceType: 'salesforce', perUser: false },
+            { name: 'warehouse', serviceType: 'clickhouse', perUser: false },
+            { name: 'inbox', serviceType: 'gmail', perUser: true },
         ], { reexportAirtable: false });
         (0, vitest_1.expect)(typeErrorsIn(generated, [
             "import { integrations } from 'zitejs/integrations';",
             'export const run = async () => {',
             "  const crm = await integrations.get('crm');",
-            "  if (crm.status === 'connected') return crm.instanceUrl + crm.accessToken;",
             "  const warehouse = await integrations.get('warehouse');",
-            "  if (warehouse.status === 'connected') return warehouse.url + warehouse.username;",
-            '  return crm.connectUrl;',
+            "  const inbox = await integrations.get('inbox');",
+            "  if (inbox.status !== 'connected') return inbox.connectUrl;",
+            '  return crm.instanceUrl + warehouse.url + inbox.accessToken;',
             '};',
         ].join('\n'))).toEqual([]);
+        (0, vitest_1.expect)(typeErrorsIn(generated, "import { integrations } from 'zitejs/integrations';\nexport const f = async () => (await integrations.get('inbox')).accessToken;")).toHaveLength(1);
         (0, vitest_1.expect)(typeErrorsIn(generated, "import { integrations } from 'zitejs/integrations';\nvoid integrations.get('nope');")).toHaveLength(1);
     });
     (0, vitest_1.it)('compiles with nothing visible, naming nothing', () => {
@@ -542,13 +547,13 @@ if (jira.status === 'connected') {
         ['a newline', 'crm\nprod'],
         ['a trailing backslash', 'crm\\'],
     ])('emits parseable TypeScript for a name with %s', (_what, name) => {
-        (0, vitest_1.expect)(syntaxErrorsIn((0, lib_js_1.generateIntegrationsIndex)([{ name, serviceType: 'slack' }], {
+        (0, vitest_1.expect)(syntaxErrorsIn((0, lib_js_1.generateIntegrationsIndex)([{ name, serviceType: 'slack', perUser: false }], {
             reexportAirtable: false,
         }))).toEqual([]);
     });
     // One module for everything integration: the Airtable clients keep resolving.
     (0, vitest_1.it)('re-exports the generated Airtable clients beside the integrations client', () => {
-        const generated = (0, lib_js_1.generateIntegrationsIndex)([{ name: 'team', serviceType: 'slack' }], { reexportAirtable: true });
+        const generated = (0, lib_js_1.generateIntegrationsIndex)([{ name: 'team', serviceType: 'slack', perUser: false }], { reexportAirtable: true });
         (0, vitest_1.expect)(generated).toContain("export * from './airtable';");
         (0, vitest_1.expect)(typeErrorsIn(generated, [
             "import { Customers, integrations } from 'zitejs/integrations';",

package/dist/esm/integrations/client.d.ts

@@ -3,12 +3,14 @@ export declare const INTEGRATIONS_CLASS_NAME = "Connections";
 /**
  * `accessToken` is the service's primary credential (for Twilio the account SID).
  * Call `get` where the value is used: a token refreshed mid-run is what the next call returns.
+ * For a workspace connection that isn't connected, `get` throws a `ZiteError`
+ * whose `userFacingMessage` is safe to show visitors.
  */
 export type Connected<Extra = {}> = {
     status: "connected";
     accessToken: string;
 } & Extra;
-/** No account behind the entry, or its token could not be refreshed. `connectUrl` is where a person fixes that. */
+/** A per-user entry the signed-in user hasn't connected, or whose token expired: send them to `connectUrl`. */
 export type NeedsConnect = {
     status: "missing" | "expired";
     connectUrl: string;
@@ -19,7 +21,8 @@ export interface IntegrationsClient<ByName extends Record<string, unknown>> {
 }
 /**
  * `ByName` maps each entry name to its answer, e.g.
- * `{ crm: Connected<{ instanceUrl: string }> | NeedsConnect }`; `zitejs generate`
- * writes it per app into `.zite/integrations/index.ts`.
+ * `{ crm: Connected<{ instanceUrl: string }>; inbox: Connected | NeedsConnect }`
+ * (only per-user entries can need connecting); `zitejs generate` writes it per
+ * app into `.zite/integrations/index.ts`.
  */
 export declare function createIntegrationsClient<ByName extends Record<string, unknown>>(): IntegrationsClient<ByName>;

package/dist/esm/integrations/client.js

@@ -1,12 +1,12 @@
 import { getSdkCall } from "../internal/sdkCall.js";
-// The worker and runner answer this call under its original name; renaming the
-// wire protocol would break every deployed bundle for no user-visible gain.
+// The platform id the worker answers `get` under, as `__pdf__` is for PDFs.
 export const INTEGRATIONS_SDK_INTEGRATION_ID = "__connections__";
 export const INTEGRATIONS_CLASS_NAME = "Connections";
 /**
  * `ByName` maps each entry name to its answer, e.g.
- * `{ crm: Connected<{ instanceUrl: string }> | NeedsConnect }`; `zitejs generate`
- * writes it per app into `.zite/integrations/index.ts`.
+ * `{ crm: Connected<{ instanceUrl: string }>; inbox: Connected | NeedsConnect }`
+ * (only per-user entries can need connecting); `zitejs generate` writes it per
+ * app into `.zite/integrations/index.ts`.
  */
 export function createIntegrationsClient() {
     return {

package/dist/esm/integrations/client.test-d.js

@@ -6,6 +6,7 @@ describe("createIntegrationsClient", () => {
     const client = createIntegrationsClient();
     it("types each name's answer", () => {
         expectTypeOf(client.get("crm")).resolves.toEqualTypeOf();
+        expectTypeOf(client.get("inbox")).resolves.toEqualTypeOf();
     });
     it("rejects a name the app cannot see", () => {
         // @ts-expect-error not a visible entry
@@ -16,23 +17,21 @@ describe("createIntegrationsClient", () => {
         const none = createIntegrationsClient();
         expectTypeOf().toEqualTypeOf();
     });
-    it("narrows to the connected fields on status", async () => {
-        const crm = await client.get("crm");
-        if (crm.status === "connected") {
-            expectTypeOf(crm.instanceUrl).toEqualTypeOf();
+    it("narrows a per-user entry to the connected fields on status", async () => {
+        const inbox = await client.get("inbox");
+        if (inbox.status === "connected") {
+            expectTypeOf(inbox.accessToken).toEqualTypeOf();
         }
         else {
-            expectTypeOf(crm.connectUrl).toEqualTypeOf();
+            expectTypeOf(inbox.connectUrl).toEqualTypeOf();
         }
     });
 });
 describe("the untyped zitejs/integrations client", () => {
     it("takes any name; only accessToken is certain", async () => {
         const entry = await untyped.get("anything");
-        if (entry.status === "connected") {
-            expectTypeOf(entry.accessToken).toEqualTypeOf();
-            expectTypeOf(entry.instanceUrl).toEqualTypeOf();
-        }
+        expectTypeOf(entry.accessToken).toEqualTypeOf();
+        expectTypeOf(entry.instanceUrl).toEqualTypeOf();
     });
 });
 describe("CREDENTIAL_FIELDS", () => {

package/dist/esm/integrations/index.d.ts

@@ -1,3 +1,3 @@
-import { type Connected, type NeedsConnect } from "./client.js";
+import { type Connected } from "./client.js";
 export type { Connected, NeedsConnect } from "./client.js";
-export declare const integrations: import("./client.js").IntegrationsClient<Record<string, NeedsConnect | Connected<Partial<Record<string, string>>>>>;
+export declare const integrations: import("./client.js").IntegrationsClient<Record<string, Connected<Partial<Record<string, string>>>>>;

package/dist/esm/integrations/index.js

@@ -1,3 +1,3 @@
-import { createIntegrationsClient, } from "./client.js";
+import { createIntegrationsClient } from "./client.js";
 // What code with no generated `.zite/integrations/index.ts` gets, e.g. a repo-root script.
 export const integrations = createIntegrationsClient();

package/dist/esm/integrations/rules.d.ts

@@ -61,9 +61,12 @@ export declare const isCredentialServiceType: (type: string) => type is Credenti
 export type GettableIntegration = {
     name: string;
     serviceType: CredentialServiceType;
+    /** Each signed-in user connects their own account, so `get` can answer that they haven't. */
+    perUser: boolean;
 };
 export type ConfigIntegrations = Readonly<Record<string, {
     type?: unknown;
+    connectionMode?: unknown;
 } | undefined>>;
 /**
  * The entries a source dir can name, by name: its own, then the workspace's under

package/dist/esm/integrations/rules.js

@@ -100,8 +100,13 @@ export const gettableIntegrations = (rootIntegrations, appIntegrations) => {
         if (typeof entry?.type !== "string")
             continue;
         const serviceType = normalizeIntegrationServiceType(entry.type);
-        if (isCredentialServiceType(serviceType))
-            visible.push({ name, serviceType });
+        if (isCredentialServiceType(serviceType)) {
+            visible.push({
+                name,
+                serviceType,
+                perUser: entry.connectionMode === "app-user",
+            });
+        }
     }
     return visible.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 };

package/dist/esm/integrations/rules.test.js

@@ -45,9 +45,9 @@ describe("normalizeIntegrationServiceType", () => {
 describe("gettableIntegrations", () => {
     it("lists the app's entries, then the workspace's under untaken keys, by name", () => {
         expect(gettableIntegrations({ crm: { type: "salesforce" }, team: { type: "slack" } }, { billing: { type: "stripe" }, team: { type: "microsoftTeams" } })).toEqual([
-            { name: "billing", serviceType: "stripe" },
-            { name: "crm", serviceType: "salesforce" },
-            { name: "team", serviceType: "microsoftTeams" },
+            { name: "billing", serviceType: "stripe", perUser: false },
+            { name: "crm", serviceType: "salesforce", perUser: false },
+            { name: "team", serviceType: "microsoftTeams", perUser: false },
         ]);
     });
     it("lets an app entry of a generated-client type shadow a workspace credential entry", () => {
@@ -68,7 +68,7 @@ describe("gettableIntegrations", () => {
     });
     it("normalizes legacy type spellings", () => {
         expect(gettableIntegrations({ cal: { type: "google-calendar" } })).toEqual([
-            { name: "cal", serviceType: "googleCalendar" },
+            { name: "cal", serviceType: "googleCalendar", perUser: false },
         ]);
     });
     it("drops a type it does not know, as the runtime does", () => {
@@ -76,7 +76,16 @@ describe("gettableIntegrations", () => {
     });
     it("shadows by own keys only", () => {
         expect(gettableIntegrations({ constructor: { type: "slack" } }, {})).toEqual([
-            { name: "constructor", serviceType: "slack" },
+            { name: "constructor", serviceType: "slack", perUser: false },
+        ]);
+    });
+    it("marks an entry each signed-in user connects for themselves", () => {
+        expect(gettableIntegrations({
+            inbox: { type: "gmail", connectionMode: "app-user" },
+            support: { type: "gmail" },
+        })).toEqual([
+            { name: "inbox", serviceType: "gmail", perUser: true },
+            { name: "support", serviceType: "gmail", perUser: false },
         ]);
     });
     it("works with no configs", () => {

package/dist/esm/sync/lib.js

@@ -1412,7 +1412,7 @@ export function generateIntegrationsIndex(entries, opts) {
         ? ["export type IntegrationByName = {};"]
         : [
             "export type IntegrationByName = {",
-            ...sorted.map(({ name, serviceType }) => `  ${tsSingleQuoted(name)}: ${connectedTypeFor(serviceType)} | NeedsConnect;`),
+            ...sorted.map(({ name, serviceType, perUser }) => `  ${tsSingleQuoted(name)}: ${connectedTypeFor(serviceType)}${perUser ? " | NeedsConnect" : ""};`),
             "};",
         ];
     return [
@@ -1422,8 +1422,10 @@ export function generateIntegrationsIndex(entries, opts) {
         "// Usage in endpoints (src/api/*.ts) and automations (src/index.ts):",
         "//   import { integrations } from 'zitejs/integrations';",
         "//",
-        "//   const crm = await integrations.get('<entry name>');",
-        "//   if (crm.status !== 'connected') { /* crm.connectUrl is where a person reconnects */ }",
+        "//   const { accessToken } = await integrations.get('<entry name>');",
+        "//",
+        "// A workspace connection that isn't connected throws a ZiteError. A per-user",
+        "// entry answers `missing`/`expired` with a connectUrl for the signed-in user.",
         "//",
         "// Call get where the value is used, not once at module scope: a token refreshed",
         "// mid-run is what the next call returns.",

package/dist/esm/sync/lib.test.js

@@ -462,8 +462,9 @@ describe('generateIntegrationsIndex', () => {
     };
     it('emits the client typed by name', () => {
         expect(generateIntegrationsIndex([
-            { name: 'team', serviceType: 'slack' },
-            { name: 'crm', serviceType: 'salesforce' },
+            { name: 'team', serviceType: 'slack', perUser: false },
+            { name: 'crm', serviceType: 'salesforce', perUser: false },
+            { name: 'inbox', serviceType: 'gmail', perUser: true },
         ], { reexportAirtable: false })).toMatchInlineSnapshot(`
       "// Auto-generated by zitejs generate from zite.config.json. Do not edit manually.
       // zitejs/integrations — an integration's credentials by its zite.config.json entry name.
@@ -471,8 +472,10 @@ describe('generateIntegrationsIndex', () => {
       // Usage in endpoints (src/api/*.ts) and automations (src/index.ts):
       //   import { integrations } from 'zitejs/integrations';
       //
-      //   const crm = await integrations.get('<entry name>');
-      //   if (crm.status !== 'connected') { /* crm.connectUrl is where a person reconnects */ }
+      //   const { accessToken } = await integrations.get('<entry name>');
+      //
+      // A workspace connection that isn't connected throws a ZiteError. A per-user
+      // entry answers \`missing\`/\`expired\` with a connectUrl for the signed-in user.
       //
       // Call get where the value is used, not once at module scope: a token refreshed
       // mid-run is what the next call returns.
@@ -482,11 +485,12 @@ describe('generateIntegrationsIndex', () => {
 
       export type { Connected, NeedsConnect };
 
-      export type IntegrationName = 'crm' | 'team';
+      export type IntegrationName = 'crm' | 'inbox' | 'team';
 
       export type IntegrationByName = {
-        'crm': Connected<{ instanceUrl: string }> | NeedsConnect;
-        'team': Connected | NeedsConnect;
+        'crm': Connected<{ instanceUrl: string }>;
+        'inbox': Connected | NeedsConnect;
+        'team': Connected;
       };
 
       export const integrations = createIntegrationsClient<IntegrationByName>();
@@ -495,33 +499,34 @@ describe('generateIntegrationsIndex', () => {
     });
     // The platform leaves these out for some accounts, so the type can't promise them.
     it('marks an extra the platform may omit as optional', () => {
-        const generated = generateIntegrationsIndex([{ name: 'tickets', serviceType: 'jira' }], { reexportAirtable: false });
-        expect(generated).toContain("'tickets': Connected<{ cloudId: string; siteUrl?: string }> | NeedsConnect;");
+        const generated = generateIntegrationsIndex([{ name: 'tickets', serviceType: 'jira', perUser: false }], { reexportAirtable: false });
+        expect(generated).toContain("'tickets': Connected<{ cloudId: string; siteUrl?: string }>;");
         expect(typeErrorsIn(generated, `import { integrations } from 'zitejs/integrations';
 const jira = await integrations.get('tickets');
-if (jira.status === 'connected') {
-  const cloudId: string = jira.cloudId;
-  const siteUrl: string = jira.siteUrl;
-}
+const cloudId: string = jira.cloudId;
+const siteUrl: string = jira.siteUrl;
 `)).toEqual([
             expect.stringContaining("Type 'string | undefined' is not assignable"),
         ]);
     });
+    // A workspace entry is used as is; only a per-user one makes code check first.
     it('types get per name in app code', () => {
         const generated = generateIntegrationsIndex([
-            { name: 'crm', serviceType: 'salesforce' },
-            { name: 'warehouse', serviceType: 'clickhouse' },
+            { name: 'crm', serviceType: 'salesforce', perUser: false },
+            { name: 'warehouse', serviceType: 'clickhouse', perUser: false },
+            { name: 'inbox', serviceType: 'gmail', perUser: true },
         ], { reexportAirtable: false });
         expect(typeErrorsIn(generated, [
             "import { integrations } from 'zitejs/integrations';",
             'export const run = async () => {',
             "  const crm = await integrations.get('crm');",
-            "  if (crm.status === 'connected') return crm.instanceUrl + crm.accessToken;",
             "  const warehouse = await integrations.get('warehouse');",
-            "  if (warehouse.status === 'connected') return warehouse.url + warehouse.username;",
-            '  return crm.connectUrl;',
+            "  const inbox = await integrations.get('inbox');",
+            "  if (inbox.status !== 'connected') return inbox.connectUrl;",
+            '  return crm.instanceUrl + warehouse.url + inbox.accessToken;',
             '};',
         ].join('\n'))).toEqual([]);
+        expect(typeErrorsIn(generated, "import { integrations } from 'zitejs/integrations';\nexport const f = async () => (await integrations.get('inbox')).accessToken;")).toHaveLength(1);
         expect(typeErrorsIn(generated, "import { integrations } from 'zitejs/integrations';\nvoid integrations.get('nope');")).toHaveLength(1);
     });
     it('compiles with nothing visible, naming nothing', () => {
@@ -537,13 +542,13 @@ if (jira.status === 'connected') {
         ['a newline', 'crm\nprod'],
         ['a trailing backslash', 'crm\\'],
     ])('emits parseable TypeScript for a name with %s', (_what, name) => {
-        expect(syntaxErrorsIn(generateIntegrationsIndex([{ name, serviceType: 'slack' }], {
+        expect(syntaxErrorsIn(generateIntegrationsIndex([{ name, serviceType: 'slack', perUser: false }], {
             reexportAirtable: false,
         }))).toEqual([]);
     });
     // One module for everything integration: the Airtable clients keep resolving.
     it('re-exports the generated Airtable clients beside the integrations client', () => {
-        const generated = generateIntegrationsIndex([{ name: 'team', serviceType: 'slack' }], { reexportAirtable: true });
+        const generated = generateIntegrationsIndex([{ name: 'team', serviceType: 'slack', perUser: false }], { reexportAirtable: true });
         expect(generated).toContain("export * from './airtable';");
         expect(typeErrorsIn(generated, [
             "import { Customers, integrations } from 'zitejs/integrations';",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zitejs",
-  "version": "0.9.129",
+  "version": "0.9.130",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "sideEffects": false,