@withone/connect 0.17.2 → 0.19.0

package/README.md

@@ -84,6 +84,41 @@ ONE_REDIRECT_URI=https://yourapp.com/api/one/callback  # exactly the registered
 ONE_PERMISSION_SET=…                                  # optional: the Permission set ID
 ```
 
+### Or from code
+
+Describe the app in `one.connect.ts` and create it with the [One CLI](https://www.npmjs.com/package/@withone/cli) (2.10.0 or later). Running it again updates the same app.
+
+```ts
+// one.connect.ts
+import { defineConnectApp } from "@withone/connect/config";
+
+export default defineConnectApp({
+  name: "Mastra",
+  logoUrl: "https://mastra.ai/logo.png",
+  redirectUris: ["http://localhost:3000/api/one/callback"],
+  ask: {
+    gmail: { access: "custom", actions: ["sendEmail", "listAndViewEmailThreads"] },
+    "google-calendar": { access: "read-only" },
+    linear: { access: "read-write" },
+  },
+});
+```
+
+```bash
+one connect types    # optional: tool slugs and action names autocomplete
+one connect create   # opens your browser to approve it, then writes .env
+```
+
+The CLI opens a page in your signed-in browser showing the app as your users will see it. You approve it there; a new app's client secret and connect key are made on that page and shown once, so they never pass through the terminal. The CLI then writes `ONE_CLIENT_ID`, `ONE_PERMISSION_SET` and `ONE_REDIRECT_URI` to `.env`. `access` is `read-only`, `read-write`, `full-access`, or `custom` with `actions`, named as `one connect types` wrote them or by id. On Node older than 22.18, name the file `one.connect.mjs` and type it with `/** @type {import("@withone/connect/config").ConnectAppConfig} */`.
+
+| Prop | |
+|---|---|
+| `name`, `redirectUris` | Required. Every callback URL, character for character. |
+| `reason` | One sentence on the card telling users why, at most 200 characters. |
+| `description`, `logoUrl`, `homepageUrl` | Optional. |
+| `branding` | `panelColor`, `buttonColor` (`#RRGGBB`), `cobrandEmail`. |
+| `ask` | Per tool slug: `access` is `read-only`, `read-write`, `full-access`, or `custom` with `actions`. Omit it to let users choose from everything they have connected. |
+
 ## 2 · The server client
 
 Your server holds one **connect key** for the app and saves one id per user who connects. Nothing expires and nothing is refreshed: One checks the user's consent on every call.
@@ -302,6 +337,21 @@ await oneConnect.runAction(userId, {
 
 `listActions(userId, platform)` lists everything a platform can do, and `runAction` takes `method` and `path` from it if you'd rather pass them yourself. `oneConnect.fetch(userId, path, init)` sends any other request to One's `/v1` API with the headers handled.
 
+### Who connected
+
+You can also read who the user is on One: their name and email. Use it if you want to, for example to show which One account is connected.
+
+```ts
+// Key mode
+const res = await oneConnect.fetch(userId, "/users/whoami");
+const { user } = await res.json(); // { id, name, email }
+
+// Token mode
+const me = await (await oneConnect.fetch(userId, "/users/me")).json(); // { firstName, lastName, email, … }
+```
+
+Users who connected with a version before 0.18.0 did not grant this, so the call returns `403` until they connect again.
+
 You never set an auth header: the client adds the connect key and the user's id to every call it makes.
 
 ## 6 · Errors
@@ -429,7 +479,7 @@ The job renews both tokens when either is within 3 days of expiring. Without it,
 | `mode` | `"key"` or `"token"`, to state the mode explicitly. |
 | `permissionSet` | The Permission set ID to ask for. |
 | `returnTo` | Where the callback sends the browser afterwards. `/` by default. |
-| `scopes` | OAuth scopes. All three spaces (personal, organization, project) by default, so the user may grant from any. |
+| `scopes` | OAuth scopes. By default `user:profile:read` (who connected) and the connections scopes of all three spaces (personal, organization, project), so the user may grant from any. |
 | `oneApiUrl` | One's API origin. Production by default. |
 
 | Method | Mode | |
@@ -469,6 +519,14 @@ The job renews both tokens when either is within 3 days of expiring. Without it,
 
 `useOneConnect` and `createConnectFlow` take `authorizeUrl`, `connectTheme`, `connector`, `returnTo`, `onSuccess`, `onError` and `onCancel`.
 
+### Config · `@withone/connect/config`
+
+| Export | |
+|---|---|
+| `defineConnectApp(config)` | Returns `config` unchanged; types `one.connect.ts`. |
+| `ConnectAppConfig`, `ConnectToolAsk`, `ConnectAccess`, `ConnectAppBranding` | The config's types. |
+| `ConnectRegistry` | Filled in by `one connect types` so slugs and action names autocomplete. |
+
 ## Support
 
 - Bugs and questions: [GitHub issues](https://github.com/withoneai/connect/issues).

package/dist/config.cjs.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * A Connect app described as code, for `one connect create`.
+ *
+ *   // one.connect.ts
+ *   import { defineConnectApp } from "@withone/connect/config";
+ *
+ *   export default defineConnectApp({
+ *     name: "Mastra",
+ *     redirectUris: ["http://localhost:3000/api/one/callback"],
+ *     ask: {
+ *       gmail: { access: "custom", actions: ["sendEmail"] },
+ *       "google-calendar": { access: "read-only" },
+ *       linear: { access: "read-write" },
+ *     },
+ *   });
+ *
+ * Types and one identity helper; nothing here calls One. `one connect
+ * create` reads the file and opens a page in your signed-in browser, where
+ * you approve the app (or, on a re-run, its new version). A new app's
+ * client secret and connect key are made and shown there once; neither is
+ * ever part of this file or passes through the CLI.
+ */
+
+/**
+ * Filled in by `one connect types`, which writes a declaration file naming
+ * every tool and, for the tools your `ask` names, every action:
+ *
+ *   declare module "@withone/connect/config" {
+ *     interface ConnectRegistry {
+ *       tools: "gmail" | "google-calendar" | "linear" | …;
+ *       actions: { gmail: "sendEmail" | "listAndViewEmailThreads" | … };
+ *     }
+ *   }
+ *
+ * Until it runs, any tool slug and any action name type-check.
+ */
+
+/** A tool's slug, as One's catalog names it: "gmail", "google-calendar". */
+
+/** An action named for the config: its title in camel case ("sendEmail"),
+ *  from the names `one connect types` wrote for that tool. */
+
+/** An action as `actions` takes it: by name, or by its id from One's
+ *  catalog (`one actions search` prints it). */
+
+/**
+ * How much of a tool the app asks for, in the dashboard's words.
+ * - `read-only`: reads only.
+ * - `read-write`: reads, creates and updates; never deletes.
+ * - `full-access`: everything the tool offers.
+ */
+
+/** One tool's ask: a level, or a hand-picked list of actions. */
+
+/** A colour as `#RRGGBB`. */
+
+/** How the connect card and its sign-in email look. Omit it to keep
+ *  One's own look. */
+
+/**
+ * Returns `config` unchanged. It exists for the editor: the argument is
+ * checked against {@link ConnectAppConfig}, and after `one connect types`
+ * tool slugs and action names autocomplete.
+ */
+function defineConnectApp(config) {
+  return config;
+}
+
+exports.defineConnectApp = defineConnectApp;

package/dist/config.d.ts

@@ -0,0 +1,102 @@
+/**
+ * A Connect app described as code, for `one connect create`.
+ *
+ *   // one.connect.ts
+ *   import { defineConnectApp } from "@withone/connect/config";
+ *
+ *   export default defineConnectApp({
+ *     name: "Mastra",
+ *     redirectUris: ["http://localhost:3000/api/one/callback"],
+ *     ask: {
+ *       gmail: { access: "custom", actions: ["sendEmail"] },
+ *       "google-calendar": { access: "read-only" },
+ *       linear: { access: "read-write" },
+ *     },
+ *   });
+ *
+ * Types and one identity helper; nothing here calls One. `one connect
+ * create` reads the file and opens a page in your signed-in browser, where
+ * you approve the app (or, on a re-run, its new version). A new app's
+ * client secret and connect key are made and shown there once; neither is
+ * ever part of this file or passes through the CLI.
+ */
+/**
+ * Filled in by `one connect types`, which writes a declaration file naming
+ * every tool and, for the tools your `ask` names, every action:
+ *
+ *   declare module "@withone/connect/config" {
+ *     interface ConnectRegistry {
+ *       tools: "gmail" | "google-calendar" | "linear" | …;
+ *       actions: { gmail: "sendEmail" | "listAndViewEmailThreads" | … };
+ *     }
+ *   }
+ *
+ * Until it runs, any tool slug and any action name type-check.
+ */
+export interface ConnectRegistry {
+}
+/** A tool's slug, as One's catalog names it: "gmail", "google-calendar". */
+export type ConnectToolSlug = ConnectRegistry extends {
+    tools: infer T extends string;
+} ? T : string;
+/** An action named for the config: its title in camel case ("sendEmail"),
+ *  from the names `one connect types` wrote for that tool. */
+export type ConnectActionName<T extends string> = ConnectRegistry extends {
+    actions: infer A;
+} ? T extends keyof A ? A[T] & string : string : string;
+/** An action as `actions` takes it: by name, or by its id from One's
+ *  catalog (`one actions search` prints it). */
+export type ConnectActionRef<T extends string> = ConnectActionName<T> | `conn_mod_def::${string}`;
+/**
+ * How much of a tool the app asks for, in the dashboard's words.
+ * - `read-only`: reads only.
+ * - `read-write`: reads, creates and updates; never deletes.
+ * - `full-access`: everything the tool offers.
+ */
+export type ConnectAccess = "read-only" | "read-write" | "full-access";
+/** One tool's ask: a level, or a hand-picked list of actions. */
+export type ConnectToolAsk<T extends string = string> = {
+    access: ConnectAccess;
+} | {
+    access: "custom";
+    actions: readonly [ConnectActionRef<T>, ...ConnectActionRef<T>[]];
+};
+/** A colour as `#RRGGBB`. */
+export type ConnectHexColor = `#${string}`;
+/** How the connect card and its sign-in email look. Omit it to keep
+ *  One's own look. */
+export interface ConnectAppBranding {
+    /** The card's side panel. */
+    panelColor: ConnectHexColor;
+    /** Authorize, Continue and the other primary buttons. */
+    buttonColor: ConnectHexColor;
+    /** Whether the sign-in email carries the app's name, logo and colours.
+     *  `false` when omitted. */
+    cobrandEmail?: boolean;
+}
+export interface ConnectAppConfig {
+    /** Shown on the connect card and in the user's list of apps. */
+    name: string;
+    /** Every callback URL the app's routes run on, character for character:
+     *  local first is fine, then production. */
+    redirectUris: readonly [string, ...string[]];
+    description?: string;
+    /** A public https URL to a square image. */
+    logoUrl?: string;
+    homepageUrl?: string;
+    /** One sentence on the card telling users why the app asks, at most
+     *  200 characters. */
+    reason?: string;
+    branding?: ConnectAppBranding;
+    /** The tools the app asks for, keyed by slug. Omit it to let users
+     *  choose from everything they have connected. */
+    ask?: {
+        [T in ConnectToolSlug]?: ConnectToolAsk<T>;
+    };
+}
+/**
+ * Returns `config` unchanged. It exists for the editor: the argument is
+ * checked against {@link ConnectAppConfig}, and after `one connect types`
+ * tool slugs and action names autocomplete.
+ */
+export declare function defineConnectApp<const C extends ConnectAppConfig>(config: C): C;

package/dist/config.esm.js

@@ -0,0 +1,69 @@
+/**
+ * A Connect app described as code, for `one connect create`.
+ *
+ *   // one.connect.ts
+ *   import { defineConnectApp } from "@withone/connect/config";
+ *
+ *   export default defineConnectApp({
+ *     name: "Mastra",
+ *     redirectUris: ["http://localhost:3000/api/one/callback"],
+ *     ask: {
+ *       gmail: { access: "custom", actions: ["sendEmail"] },
+ *       "google-calendar": { access: "read-only" },
+ *       linear: { access: "read-write" },
+ *     },
+ *   });
+ *
+ * Types and one identity helper; nothing here calls One. `one connect
+ * create` reads the file and opens a page in your signed-in browser, where
+ * you approve the app (or, on a re-run, its new version). A new app's
+ * client secret and connect key are made and shown there once; neither is
+ * ever part of this file or passes through the CLI.
+ */
+
+/**
+ * Filled in by `one connect types`, which writes a declaration file naming
+ * every tool and, for the tools your `ask` names, every action:
+ *
+ *   declare module "@withone/connect/config" {
+ *     interface ConnectRegistry {
+ *       tools: "gmail" | "google-calendar" | "linear" | …;
+ *       actions: { gmail: "sendEmail" | "listAndViewEmailThreads" | … };
+ *     }
+ *   }
+ *
+ * Until it runs, any tool slug and any action name type-check.
+ */
+
+/** A tool's slug, as One's catalog names it: "gmail", "google-calendar". */
+
+/** An action named for the config: its title in camel case ("sendEmail"),
+ *  from the names `one connect types` wrote for that tool. */
+
+/** An action as `actions` takes it: by name, or by its id from One's
+ *  catalog (`one actions search` prints it). */
+
+/**
+ * How much of a tool the app asks for, in the dashboard's words.
+ * - `read-only`: reads only.
+ * - `read-write`: reads, creates and updates; never deletes.
+ * - `full-access`: everything the tool offers.
+ */
+
+/** One tool's ask: a level, or a hand-picked list of actions. */
+
+/** A colour as `#RRGGBB`. */
+
+/** How the connect card and its sign-in email look. Omit it to keep
+ *  One's own look. */
+
+/**
+ * Returns `config` unchanged. It exists for the editor: the argument is
+ * checked against {@link ConnectAppConfig}, and after `one connect types`
+ * tool slugs and action names autocomplete.
+ */
+function defineConnectApp(config) {
+  return config;
+}
+
+export { defineConnectApp };

package/dist/server/index.cjs.js

@@ -20,7 +20,10 @@ const TX_COOKIE_PREFIX = "one_tx_";
  *  legitimate callback can arrive up to twenty minutes after the start.
  *  Thirty minutes leaves a margin. */
 const TX_COOKIE_MAX_AGE_SECONDS = 1800;
-const DEFAULT_SCOPES = ["user:connections:read", "user:connections:write", "org:connections:read", "org:connections:write", "project:connections:read", "project:connections:write"];
+const DEFAULT_SCOPES = [
+// Who connected: lets the app read the user's name and email from
+// /v1/users/whoami (key mode) or /v1/users/me (token mode).
+"user:profile:read", "user:connections:read", "user:connections:write", "org:connections:read", "org:connections:write", "project:connections:read", "project:connections:write"];
 function createState() {
   return node_crypto.randomBytes(16).toString("hex");
 }

package/dist/server/index.esm.js

@@ -18,7 +18,10 @@ const TX_COOKIE_PREFIX = "one_tx_";
  *  legitimate callback can arrive up to twenty minutes after the start.
  *  Thirty minutes leaves a margin. */
 const TX_COOKIE_MAX_AGE_SECONDS = 1800;
-const DEFAULT_SCOPES = ["user:connections:read", "user:connections:write", "org:connections:read", "org:connections:write", "project:connections:read", "project:connections:write"];
+const DEFAULT_SCOPES = [
+// Who connected: lets the app read the user's name and email from
+// /v1/users/whoami (key mode) or /v1/users/me (token mode).
+"user:profile:read", "user:connections:read", "user:connections:write", "org:connections:read", "org:connections:write", "project:connections:read", "project:connections:write"];
 function createState() {
   return randomBytes(16).toString("hex");
 }

package/dist/server/types.d.ts

@@ -102,7 +102,8 @@ export interface OneConnectBaseConfig {
     /** Where the callback sends the browser afterwards. "/" when omitted;
      *  the outcome is appended as `?one_connect=…`. */
     returnTo?: string;
-    /** OAuth scopes. All three tenancy tiers when omitted, so the user may
+    /** OAuth scopes. When omitted: `user:profile:read` (who connected) and
+     *  the connections scopes of all three tenancy tiers, so the user may
      *  grant from any space. */
     scopes?: string[];
 }

package/dist/types.d.ts

@@ -77,9 +77,9 @@ export interface ConnectButtonLogo {
     name: string;
     imageUrl: string;
 }
-/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in 0.18.0. */
+/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in 0.20.0. */
 export type ConnectButtonPlatformInput = ConnectButtonLogoInput;
-/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.18.0. */
+/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.20.0. */
 export type ConnectButtonPlatform = ConnectButtonLogo;
 export type ConnectButtonVariant = "default" | "accent" | "block";
 export type ConnectButtonSize = "sm" | "md" | "lg";
@@ -94,7 +94,7 @@ export interface ConnectButtonProps {
      *  into a "+N" chip. Decoration only; the permission set decides what
      *  One asks for. */
     logos?: ConnectButtonLogoInput[];
-    /** @deprecated Renamed to `logos`; removed in 0.18.0. */
+    /** @deprecated Renamed to `logos`; removed in 0.20.0. */
     platforms?: ConnectButtonLogoInput[];
     /** Whether this user has a live grant, from your server. When set, it
      *  decides the Connected state. When omitted, the button shows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "One Connect for your app: the button your users press, the two backend routes as one import, and a server client that calls One with the grant. Users keep their connections in One; your app holds only what they granted.",
   "files": [
     "dist",
@@ -105,6 +105,11 @@
       "import": "./dist/node.esm.js",
       "require": "./dist/node.cjs.js"
     },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.esm.js",
+      "require": "./dist/config.cjs.js"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {

package/skills/one-connect/SKILL.md

@@ -39,7 +39,66 @@ key mode; section 10 lists what changes for token mode.
 
 ## 2 - Ask the human for these
 
-They create the app in the One dashboard: Developers -> Connect -> New app.
+If the human has the One CLI (2.10.0 or later), create the app from code
+instead of asking for its values.
+
+**Before you start.** The CLI must be logged in: `one login` (or
+`one init`) gives the CLI its own One API key, kept in `~/.one`. Never put
+that key in the app's `.env`; the app never needs it. Install the SDK in the
+project first (`npm i @withone/connect`, 0.19.0 or later): the config file
+imports it.
+
+**1. Write `one.connect.ts`** at the project root:
+
+```ts
+import { defineConnectApp } from "@withone/connect/config";
+
+export default defineConnectApp({
+  name: "Acme Assistant",                                // shown on the connect card
+  redirectUris: ["http://localhost:3000/api/one/callback"], // every callback URL, exact
+  reason: "Acme Assistant reads your mail and plans your week", // optional, at most 200 characters
+  description: "Your inbox and calendar, planned",       // optional
+  logoUrl: "https://acme.app/logo.png",                  // optional, square, public https
+  homepageUrl: "https://acme.app",                       // optional
+  branding: { panelColor: "#0A0C0B", buttonColor: "#0A0C0B", cobrandEmail: false }, // optional
+  ask: {                                                 // optional: omit to let users pick from everything they have
+    gmail: { access: "custom", actions: ["sendEmail", "listAndViewEmailThreads"] },
+    "google-calendar": { access: "full-access" },
+    notion: { access: "read-write" },
+  },
+});
+```
+
+Each tool in `ask` is keyed by its slug and takes `access`: `read-only`,
+`read-write` (no deletes), `full-access`, or `custom` with `actions`.
+
+**2. Find slugs and action names** with the CLI, which reads One's catalog
+with its own key:
+
+```bash
+one connect types                                  # writes one-connect-env.d.ts: every slug, and action names for the tools in ask
+one --agent platforms                              # every tool slug
+one --agent actions find gmail "send an email" --no-knowledge   # an action's id and title
+```
+
+Use the names `one connect types` wrote, or an action's id
+(`conn_mod_def::…`). A wrong name stops `connect create` before anything
+is made.
+
+**3. Run `one --agent connect create`.** It opens a page in the human's
+browser and waits up to 10 minutes, so run it in the background or with a
+long timeout; the link goes to stderr at once, so pass it on if no browser
+opened. The human sees the app as their users will, and approves it. For a
+new app that page makes `ONE_CLIENT_SECRET` and `ONE_CONNECT_KEY` and shows
+them once: tell the human to copy both into `.env`. Once approved, the CLI
+writes `ONE_CLIENT_ID`, `ONE_PERMISSION_SET` and `ONE_REDIRECT_URI` to
+`.env` and prints `"outcome": "created"`.
+
+**To change the app later,** edit `one.connect.ts` and run
+`one --agent connect create` again. The human approves the new version in
+the browser (`"outcome": "updated"`); the secrets stay as they are.
+
+Otherwise they create the app in the One dashboard: Developers -> Connect -> New app.
 
 | Value | Notes |
 |---|---|
@@ -225,6 +284,15 @@ itself (tag `custom`), and encodes the body as asked. `listActions(userId,
 platform)` lists a whole catalog when search is not enough;
 `oneConnect.fetch(userId, path, init)` reaches any other `/v1` endpoint.
 
+**Who connected.** The app can also read who the user is on One, their
+name and email, if it wants to (for example to show which One account is
+connected). Key mode: `oneConnect.fetch(userId, "/users/whoami")` returns
+`{ user: { id, name, email }, organization, project }`. Token mode:
+`oneConnect.fetch(userId, "/users/me")` returns `{ firstName, lastName,
+email, … }`. A user who connected before 0.18.0 gets `403` until they
+connect again. Mention this to the human as something available; whether
+and where to show it is their choice.
+
 Do not set any auth header. The package adds the connect key and the
 user's id to every call it makes.
 

package/src/config.ts

@@ -0,0 +1,120 @@
+/**
+ * A Connect app described as code, for `one connect create`.
+ *
+ *   // one.connect.ts
+ *   import { defineConnectApp } from "@withone/connect/config";
+ *
+ *   export default defineConnectApp({
+ *     name: "Mastra",
+ *     redirectUris: ["http://localhost:3000/api/one/callback"],
+ *     ask: {
+ *       gmail: { access: "custom", actions: ["sendEmail"] },
+ *       "google-calendar": { access: "read-only" },
+ *       linear: { access: "read-write" },
+ *     },
+ *   });
+ *
+ * Types and one identity helper; nothing here calls One. `one connect
+ * create` reads the file and opens a page in your signed-in browser, where
+ * you approve the app (or, on a re-run, its new version). A new app's
+ * client secret and connect key are made and shown there once; neither is
+ * ever part of this file or passes through the CLI.
+ */
+
+/**
+ * Filled in by `one connect types`, which writes a declaration file naming
+ * every tool and, for the tools your `ask` names, every action:
+ *
+ *   declare module "@withone/connect/config" {
+ *     interface ConnectRegistry {
+ *       tools: "gmail" | "google-calendar" | "linear" | …;
+ *       actions: { gmail: "sendEmail" | "listAndViewEmailThreads" | … };
+ *     }
+ *   }
+ *
+ * Until it runs, any tool slug and any action name type-check.
+ */
+export interface ConnectRegistry {}
+
+/** A tool's slug, as One's catalog names it: "gmail", "google-calendar". */
+export type ConnectToolSlug = ConnectRegistry extends {
+  tools: infer T extends string;
+}
+  ? T
+  : string;
+
+/** An action named for the config: its title in camel case ("sendEmail"),
+ *  from the names `one connect types` wrote for that tool. */
+export type ConnectActionName<T extends string> = ConnectRegistry extends {
+  actions: infer A;
+}
+  ? T extends keyof A
+    ? A[T] & string
+    : string
+  : string;
+
+/** An action as `actions` takes it: by name, or by its id from One's
+ *  catalog (`one actions search` prints it). */
+export type ConnectActionRef<T extends string> =
+  ConnectActionName<T> | `conn_mod_def::${string}`;
+
+/**
+ * How much of a tool the app asks for, in the dashboard's words.
+ * - `read-only`: reads only.
+ * - `read-write`: reads, creates and updates; never deletes.
+ * - `full-access`: everything the tool offers.
+ */
+export type ConnectAccess = "read-only" | "read-write" | "full-access";
+
+/** One tool's ask: a level, or a hand-picked list of actions. */
+export type ConnectToolAsk<T extends string = string> =
+  | { access: ConnectAccess }
+  | {
+      access: "custom";
+      actions: readonly [ConnectActionRef<T>, ...ConnectActionRef<T>[]];
+    };
+
+/** A colour as `#RRGGBB`. */
+export type ConnectHexColor = `#${string}`;
+
+/** How the connect card and its sign-in email look. Omit it to keep
+ *  One's own look. */
+export interface ConnectAppBranding {
+  /** The card's side panel. */
+  panelColor: ConnectHexColor;
+  /** Authorize, Continue and the other primary buttons. */
+  buttonColor: ConnectHexColor;
+  /** Whether the sign-in email carries the app's name, logo and colours.
+   *  `false` when omitted. */
+  cobrandEmail?: boolean;
+}
+
+export interface ConnectAppConfig {
+  /** Shown on the connect card and in the user's list of apps. */
+  name: string;
+  /** Every callback URL the app's routes run on, character for character:
+   *  local first is fine, then production. */
+  redirectUris: readonly [string, ...string[]];
+  description?: string;
+  /** A public https URL to a square image. */
+  logoUrl?: string;
+  homepageUrl?: string;
+  /** One sentence on the card telling users why the app asks, at most
+   *  200 characters. */
+  reason?: string;
+  branding?: ConnectAppBranding;
+  /** The tools the app asks for, keyed by slug. Omit it to let users
+   *  choose from everything they have connected. */
+  ask?: { [T in ConnectToolSlug]?: ConnectToolAsk<T> };
+}
+
+/**
+ * Returns `config` unchanged. It exists for the editor: the argument is
+ * checked against {@link ConnectAppConfig}, and after `one connect types`
+ * tool slugs and action names autocomplete.
+ */
+export function defineConnectApp<const C extends ConnectAppConfig>(
+  config: C,
+): C {
+  return config;
+}

package/src/server/oauth.ts

@@ -12,6 +12,9 @@ export const TX_COOKIE_PREFIX = "one_tx_";
 export const TX_COOKIE_MAX_AGE_SECONDS = 1800;
 
 export const DEFAULT_SCOPES = [
+  // Who connected: lets the app read the user's name and email from
+  // /v1/users/whoami (key mode) or /v1/users/me (token mode).
+  "user:profile:read",
   "user:connections:read",
   "user:connections:write",
   "org:connections:read",

package/src/server/types.ts

@@ -109,7 +109,8 @@ export interface OneConnectBaseConfig {
   /** Where the callback sends the browser afterwards. "/" when omitted;
    *  the outcome is appended as `?one_connect=…`. */
   returnTo?: string;
-  /** OAuth scopes. All three tenancy tiers when omitted, so the user may
+  /** OAuth scopes. When omitted: `user:profile:read` (who connected) and
+   *  the connections scopes of all three tenancy tiers, so the user may
    *  grant from any space. */
   scopes?: string[];
 }

package/src/types.ts

@@ -83,9 +83,9 @@ export interface ConnectButtonLogo {
   imageUrl: string;
 }
 
-/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in 0.18.0. */
+/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in 0.20.0. */
 export type ConnectButtonPlatformInput = ConnectButtonLogoInput;
-/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.18.0. */
+/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.20.0. */
 export type ConnectButtonPlatform = ConnectButtonLogo;
 
 export type ConnectButtonVariant = "default" | "accent" | "block";
@@ -102,7 +102,7 @@ export interface ConnectButtonProps {
    *  into a "+N" chip. Decoration only; the permission set decides what
    *  One asks for. */
   logos?: ConnectButtonLogoInput[];
-  /** @deprecated Renamed to `logos`; removed in 0.18.0. */
+  /** @deprecated Renamed to `logos`; removed in 0.20.0. */
   platforms?: ConnectButtonLogoInput[];
   /** Whether this user has a live grant, from your server. When set, it
    *  decides the Connected state. When omitted, the button shows