@withone/connect 0.17.1 → 0.18.0

package/README.md

@@ -21,7 +21,7 @@
   <a href="https://withone.ai/products/connect"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.withone.ai%2Fv1%2Favailable-connectors%3Flimit%3D1&query=%24.total&label=connectors" alt="Live count of connectors on One"></a>
 </p>
 
-One Connect lets your users grant your app **scoped, revocable access to their own tools**: Gmail, Slack, Notion, Stripe and 900+ more. The connections stay in your user's One account. Your app holds only what they granted, and One checks that on every call.
+One Connect lets your users grant your app **scoped, revocable access to their own tools**: Gmail, Slack, Notion, Stripe and the rest of 1,000+ platforms, with 130,000+ actions between them. The connections stay in your user's One account. Your app holds only what they granted, and One checks that on every call.
 
 You add three things: a button, two backend routes, and the calls you make with the grant.
 
@@ -302,6 +302,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 +444,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 | |

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.19.0. */
 export type ConnectButtonPlatformInput = ConnectButtonLogoInput;
-/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.18.0. */
+/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.19.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.19.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.1",
+  "version": "0.18.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",

package/skills/one-connect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: one-connect
-description: Add One Connect to an application so its users can grant the app scoped, revocable access to their own One-connected tools (Gmail, Slack, Notion, Stripe and 900+ more). Use when wiring @withone/connect into an app - choosing key or token mode, the two backend routes, the Connect button or the app's own button, and calling One with the grant.
+description: Add One Connect to an application so its users can grant the app scoped, revocable access to their own One-connected tools (Gmail, Slack, Notion, Stripe and the rest of 1,000+ platforms). Use when wiring @withone/connect into an app - choosing key or token mode, the two backend routes, the Connect button or the app's own button, and calling One with the grant.
 ---
 
 # One Connect
@@ -225,6 +225,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/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.19.0. */
 export type ConnectButtonPlatformInput = ConnectButtonLogoInput;
-/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.18.0. */
+/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.19.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.19.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