@withone/connect 0.16.1 → 0.17.1

package/dist/server/index.cjs.js

@@ -34,14 +34,40 @@ function txCookieName(state) {
   return `${TX_COOKIE_PREFIX}${state}`;
 }
 
+/** A return path this one flow may use: a path on the app itself. A
+ *  full URL, a protocol-relative one or anything else is dropped, so
+ *  the callback never sends a user to another site. */
+function appPath(value) {
+  if (!value || !value.startsWith("/")) return undefined;
+  if (value.startsWith("//") || value.startsWith("/\\")) return undefined;
+  return value;
+}
+
+/** The cookie value: the verifier, then the flow's own return path when
+ *  it has one. A dot separates them; the verifier is base64url, which
+ *  never contains one, so a value written before 0.17 still reads. */
+function txCookieValue(verifier, returnTo) {
+  return returnTo ? `${verifier}.${Buffer.from(returnTo).toString("base64url")}` : verifier;
+}
+function parseTxCookieValue(value) {
+  const dot = value.indexOf(".");
+  if (dot < 0) return {
+    verifier: value
+  };
+  return {
+    verifier: value.slice(0, dot),
+    returnTo: appPath(Buffer.from(value.slice(dot + 1), "base64url").toString())
+  };
+}
+
 /** The cookie scoped to the routes that need it: the directory of the
  *  callback path, which is also where the authorize route lives. */
-function txCookie(state, verifier, redirectUri) {
+function txCookie(state, verifier, redirectUri, returnTo) {
   const url = new URL(redirectUri);
   const path = url.pathname.replace(/\/[^/]*$/, "") || "/";
   return {
     name: txCookieName(state),
-    value: verifier,
+    value: txCookieValue(verifier, returnTo),
     options: {
       httpOnly: true,
       secure: url.protocol === "https:",
@@ -159,6 +185,18 @@ function tokenScopes(accessToken) {
  * method and path the SDK runs it with.
  */
 
+/**
+ * Why One itself turned a call down, when it did. A provider's own error
+ * (Gmail's 404, Stripe's 400) is not One's refusal and reads `null`.
+ *
+ * - `grant`: the call is outside what the user granted (403). Do not retry.
+ * - `plan_limit`: a plan limit was hit (402, "Please try again later or
+ *   upgrade your plan"). Not about the grant: wait and retry later.
+ * - `rate_limit`: too many calls (429). Wait and retry later.
+ * - `one_error`: any other error from One (for example a 5xx). Retry with
+ *   a backoff.
+ */
+
 /**
  * - `not_connected`: nothing is stored for this user.
  * - `reconnect_required` (key mode): One will not act for this user.
@@ -484,6 +522,23 @@ function createTokenCredential(tokenStore, postToken) {
  * The Next.js and Node adapters turn the first two into route handlers.
  * See `./key` and `./token` for what each mode stores and sends.
  */
+
+/**
+ * Why One itself refused a call, from its reply. One's own errors carry a
+ * correlationId; a provider's error does not, so it reads `null`. Only a
+ * 403 is the grant: One also answers a plan limit (402), a rate limit
+ * (429) and its own failures (5xx) with a correlationId, and none of those
+ * mean the call is outside what the user granted.
+ */
+function oneRefusal(response, data) {
+  if (response.ok) return null;
+  const fromOne = typeof data === "object" && data !== null && "correlationId" in data;
+  if (!fromOne) return null;
+  if (response.status === 403) return "grant";
+  if (response.status === 402) return "plan_limit";
+  if (response.status === 429) return "rate_limit";
+  return "one_error";
+}
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
 const SEARCH_DEFAULT_LIMIT = 5;
@@ -563,8 +618,8 @@ function createOneConnect(config) {
   const apiUrl = `${oneApiUrl}/v1`;
   const returnTo = config.returnTo ?? "/";
   const scopes = config.scopes ?? DEFAULT_SCOPES;
-  const returnUrl = (status, code) => {
-    const url = new URL(returnTo, config.redirectUri);
+  const returnUrl = (status, code, flowReturnTo) => {
+    const url = new URL(flowReturnTo ?? returnTo, config.redirectUri);
     url.searchParams.set(RETURN_STATUS_PARAM, status);
     if (code) url.searchParams.set(RETURN_ERROR_PARAM, code);
     return url.toString();
@@ -623,7 +678,7 @@ function createOneConnect(config) {
     if (input.loginHint) url.searchParams.set("login_hint", input.loginHint);
     return {
       redirectUrl: url.toString(),
-      cookie: txCookie(state, verifier, config.redirectUri)
+      cookie: txCookie(state, verifier, config.redirectUri, appPath(input.returnTo))
     };
   };
   const completeAuthorization = async input => {
@@ -632,12 +687,19 @@ function createOneConnect(config) {
     const state = params.get("state");
     const oauthError = params.get("error");
     const cookieName = state ? txCookieName(state) : undefined;
-    const verifier = cookieName ? input.getCookie(cookieName) : undefined;
+    const stored = cookieName ? input.getCookie(cookieName) : undefined;
+    const {
+      verifier,
+      returnTo: flowReturnTo
+    } = stored ? parseTxCookieValue(stored) : {
+      verifier: undefined,
+      returnTo: undefined
+    };
     const fail = (failure, message) => ({
       outcome: failure === "declined" ? "declined" : "failed",
       code: failure,
       message,
-      redirectUrl: returnUrl("error", failure),
+      redirectUrl: returnUrl("error", failure, flowReturnTo),
       clearCookieName: cookieName
     });
     if (oauthError === "access_denied") return fail("declined", "The user cancelled on One's page.");
@@ -660,7 +722,7 @@ function createOneConnect(config) {
     }
     return {
       outcome: "connected",
-      redirectUrl: returnUrl("success"),
+      redirectUrl: returnUrl("success", undefined, flowReturnTo),
       clearCookieName: cookieName
     };
   };
@@ -827,6 +889,7 @@ function createOneConnect(config) {
           status: response.status,
           ok: false,
           blockedByGrant: true,
+          refusal: "grant",
           data: text
         };
         throw refused;
@@ -840,13 +903,12 @@ function createOneConnect(config) {
     } catch {
       /* the provider answered with something other than JSON */
     }
-    // One's own refusals carry a correlationId; a provider's error does
-    // not. A One-shaped 403 is the grant working, not the provider.
-    const blockedByGrant = !response.ok && typeof data === "object" && data !== null && "correlationId" in data;
+    const refusal = oneRefusal(response, data);
     return {
       status: response.status,
       ok: response.ok,
-      blockedByGrant,
+      blockedByGrant: refusal === "grant",
+      refusal,
       data
     };
   };

package/dist/server/index.esm.js

@@ -32,14 +32,40 @@ function txCookieName(state) {
   return `${TX_COOKIE_PREFIX}${state}`;
 }
 
+/** A return path this one flow may use: a path on the app itself. A
+ *  full URL, a protocol-relative one or anything else is dropped, so
+ *  the callback never sends a user to another site. */
+function appPath(value) {
+  if (!value || !value.startsWith("/")) return undefined;
+  if (value.startsWith("//") || value.startsWith("/\\")) return undefined;
+  return value;
+}
+
+/** The cookie value: the verifier, then the flow's own return path when
+ *  it has one. A dot separates them; the verifier is base64url, which
+ *  never contains one, so a value written before 0.17 still reads. */
+function txCookieValue(verifier, returnTo) {
+  return returnTo ? `${verifier}.${Buffer.from(returnTo).toString("base64url")}` : verifier;
+}
+function parseTxCookieValue(value) {
+  const dot = value.indexOf(".");
+  if (dot < 0) return {
+    verifier: value
+  };
+  return {
+    verifier: value.slice(0, dot),
+    returnTo: appPath(Buffer.from(value.slice(dot + 1), "base64url").toString())
+  };
+}
+
 /** The cookie scoped to the routes that need it: the directory of the
  *  callback path, which is also where the authorize route lives. */
-function txCookie(state, verifier, redirectUri) {
+function txCookie(state, verifier, redirectUri, returnTo) {
   const url = new URL(redirectUri);
   const path = url.pathname.replace(/\/[^/]*$/, "") || "/";
   return {
     name: txCookieName(state),
-    value: verifier,
+    value: txCookieValue(verifier, returnTo),
     options: {
       httpOnly: true,
       secure: url.protocol === "https:",
@@ -157,6 +183,18 @@ function tokenScopes(accessToken) {
  * method and path the SDK runs it with.
  */
 
+/**
+ * Why One itself turned a call down, when it did. A provider's own error
+ * (Gmail's 404, Stripe's 400) is not One's refusal and reads `null`.
+ *
+ * - `grant`: the call is outside what the user granted (403). Do not retry.
+ * - `plan_limit`: a plan limit was hit (402, "Please try again later or
+ *   upgrade your plan"). Not about the grant: wait and retry later.
+ * - `rate_limit`: too many calls (429). Wait and retry later.
+ * - `one_error`: any other error from One (for example a 5xx). Retry with
+ *   a backoff.
+ */
+
 /**
  * - `not_connected`: nothing is stored for this user.
  * - `reconnect_required` (key mode): One will not act for this user.
@@ -482,6 +520,23 @@ function createTokenCredential(tokenStore, postToken) {
  * The Next.js and Node adapters turn the first two into route handlers.
  * See `./key` and `./token` for what each mode stores and sends.
  */
+
+/**
+ * Why One itself refused a call, from its reply. One's own errors carry a
+ * correlationId; a provider's error does not, so it reads `null`. Only a
+ * 403 is the grant: One also answers a plan limit (402), a rate limit
+ * (429) and its own failures (5xx) with a correlationId, and none of those
+ * mean the call is outside what the user granted.
+ */
+function oneRefusal(response, data) {
+  if (response.ok) return null;
+  const fromOne = typeof data === "object" && data !== null && "correlationId" in data;
+  if (!fromOne) return null;
+  if (response.status === 403) return "grant";
+  if (response.status === 402) return "plan_limit";
+  if (response.status === 429) return "rate_limit";
+  return "one_error";
+}
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
 const SEARCH_DEFAULT_LIMIT = 5;
@@ -561,8 +616,8 @@ function createOneConnect(config) {
   const apiUrl = `${oneApiUrl}/v1`;
   const returnTo = config.returnTo ?? "/";
   const scopes = config.scopes ?? DEFAULT_SCOPES;
-  const returnUrl = (status, code) => {
-    const url = new URL(returnTo, config.redirectUri);
+  const returnUrl = (status, code, flowReturnTo) => {
+    const url = new URL(flowReturnTo ?? returnTo, config.redirectUri);
     url.searchParams.set(RETURN_STATUS_PARAM, status);
     if (code) url.searchParams.set(RETURN_ERROR_PARAM, code);
     return url.toString();
@@ -621,7 +676,7 @@ function createOneConnect(config) {
     if (input.loginHint) url.searchParams.set("login_hint", input.loginHint);
     return {
       redirectUrl: url.toString(),
-      cookie: txCookie(state, verifier, config.redirectUri)
+      cookie: txCookie(state, verifier, config.redirectUri, appPath(input.returnTo))
     };
   };
   const completeAuthorization = async input => {
@@ -630,12 +685,19 @@ function createOneConnect(config) {
     const state = params.get("state");
     const oauthError = params.get("error");
     const cookieName = state ? txCookieName(state) : undefined;
-    const verifier = cookieName ? input.getCookie(cookieName) : undefined;
+    const stored = cookieName ? input.getCookie(cookieName) : undefined;
+    const {
+      verifier,
+      returnTo: flowReturnTo
+    } = stored ? parseTxCookieValue(stored) : {
+      verifier: undefined,
+      returnTo: undefined
+    };
     const fail = (failure, message) => ({
       outcome: failure === "declined" ? "declined" : "failed",
       code: failure,
       message,
-      redirectUrl: returnUrl("error", failure),
+      redirectUrl: returnUrl("error", failure, flowReturnTo),
       clearCookieName: cookieName
     });
     if (oauthError === "access_denied") return fail("declined", "The user cancelled on One's page.");
@@ -658,7 +720,7 @@ function createOneConnect(config) {
     }
     return {
       outcome: "connected",
-      redirectUrl: returnUrl("success"),
+      redirectUrl: returnUrl("success", undefined, flowReturnTo),
       clearCookieName: cookieName
     };
   };
@@ -825,6 +887,7 @@ function createOneConnect(config) {
           status: response.status,
           ok: false,
           blockedByGrant: true,
+          refusal: "grant",
           data: text
         };
         throw refused;
@@ -838,13 +901,12 @@ function createOneConnect(config) {
     } catch {
       /* the provider answered with something other than JSON */
     }
-    // One's own refusals carry a correlationId; a provider's error does
-    // not. A One-shaped 403 is the grant working, not the provider.
-    const blockedByGrant = !response.ok && typeof data === "object" && data !== null && "correlationId" in data;
+    const refusal = oneRefusal(response, data);
     return {
       status: response.status,
       ok: response.ok,
-      blockedByGrant,
+      blockedByGrant: refusal === "grant",
+      refusal,
       data
     };
   };

package/dist/server/oauth.d.ts

@@ -11,9 +11,21 @@ export declare function createState(): string;
 export declare function createPkceVerifier(): string;
 export declare function pkceChallenge(verifier: string): string;
 export declare function txCookieName(state: string): string;
+/** A return path this one flow may use: a path on the app itself. A
+ *  full URL, a protocol-relative one or anything else is dropped, so
+ *  the callback never sends a user to another site. */
+export declare function appPath(value: string | undefined): string | undefined;
+/** The cookie value: the verifier, then the flow's own return path when
+ *  it has one. A dot separates them; the verifier is base64url, which
+ *  never contains one, so a value written before 0.17 still reads. */
+export declare function txCookieValue(verifier: string, returnTo?: string): string;
+export declare function parseTxCookieValue(value: string): {
+    verifier: string;
+    returnTo?: string;
+};
 /** The cookie scoped to the routes that need it: the directory of the
  *  callback path, which is also where the authorize route lives. */
-export declare function txCookie(state: string, verifier: string, redirectUri: string): OneConnectCookie;
+export declare function txCookie(state: string, verifier: string, redirectUri: string, returnTo?: string): OneConnectCookie;
 export declare function basicAuthorization(clientId: string, clientSecret: string): string;
 /** The tenant headers a grant needs on every call. A grant made into an
  *  organization or project lives there; One resolves the tenant from

package/dist/server/types.d.ts

@@ -149,6 +149,10 @@ export interface OneConnectCookie {
 export interface StartAuthorizationInput {
     /** Pre-fills the sign-in email on One's page. Never locks it. */
     loginHint?: string;
+    /** Where this one flow returns to: a path on your app ("/chat/42").
+     *  Kept in the flow's cookie, never sent to One. Anything that is not
+     *  a plain path is ignored and the configured `returnTo` applies. */
+    returnTo?: string;
 }
 export interface StartAuthorizationResult {
     /** Send the browser here with a 302. */
@@ -256,13 +260,30 @@ export interface RunActionInput {
      *  notation); "multipart" for file-style uploads. */
     encoding?: ActionBodyEncoding;
 }
+/**
+ * Why One itself turned a call down, when it did. A provider's own error
+ * (Gmail's 404, Stripe's 400) is not One's refusal and reads `null`.
+ *
+ * - `grant`: the call is outside what the user granted (403). Do not retry.
+ * - `plan_limit`: a plan limit was hit (402, "Please try again later or
+ *   upgrade your plan"). Not about the grant: wait and retry later.
+ * - `rate_limit`: too many calls (429). Wait and retry later.
+ * - `one_error`: any other error from One (for example a 5xx). Retry with
+ *   a backoff.
+ */
+export type OneRefusal = "grant" | "plan_limit" | "rate_limit" | "one_error";
 export interface RunActionResult {
     status: number;
     ok: boolean;
-    /** True when One refused the call because it is outside the grant.
-     *  The provider was never called. Do not retry. Key mode sets it; in
-     *  token mode it stays false today, so treat any 403 there as refused. */
+    /** True only when One refused the call because it is outside the grant
+     *  (a 403). The provider was never called. Do not retry. Key mode sets
+     *  it; in token mode it stays false today, so treat any 403 there as
+     *  refused. One's other refusals (plan limit, rate limit, its own
+     *  errors) are not about the grant: see `refusal`. */
     blockedByGrant: boolean;
+    /** Why One turned the call down, or `null` when it didn't (the call
+     *  succeeded, or the provider answered with its own error). */
+    refusal: OneRefusal | null;
     data: unknown;
 }
 /**

package/dist/types.d.ts

@@ -27,6 +27,14 @@ export interface OneConnectFlowOptions {
     /** Theme for One's hosted page. Carried on the URL fragment, which
      *  survives the redirect chain, so the backend forwards nothing. */
     connectTheme?: OneConnectTheme;
+    /** A connector slug ("gmail"). One's page opens that connector's
+     *  connect screen first, then shows the full list as usual. Carried
+     *  on the URL fragment like the theme. */
+    connector?: string;
+    /** Where the user lands afterwards, for this flow only: a path on
+     *  your app such as "/chat/42". Your authorize route reads it and
+     *  the callback uses it instead of the server's `returnTo`. */
+    returnTo?: string;
     /** The grant completed and the backend stored the tokens. Fires once
      *  per page load, on the first flow still mounted when the tab
      *  returns. Treat it as a hint to refetch: your server is the truth. */
@@ -69,9 +77,9 @@ export interface ConnectButtonLogo {
     name: string;
     imageUrl: string;
 }
-/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in 0.17.0. */
+/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in 0.18.0. */
 export type ConnectButtonPlatformInput = ConnectButtonLogoInput;
-/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.17.0. */
+/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.18.0. */
 export type ConnectButtonPlatform = ConnectButtonLogo;
 export type ConnectButtonVariant = "default" | "accent" | "block";
 export type ConnectButtonSize = "sm" | "md" | "lg";
@@ -86,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.17.0. */
+    /** @deprecated Renamed to `logos`; removed in 0.18.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
@@ -105,6 +113,10 @@ export interface ConnectButtonProps {
     theme?: ConnectButtonTheme;
     /** Theme of One's hosted page. */
     connectTheme?: OneConnectTheme;
+    /** A connector slug ("gmail") to open first on One's page. */
+    connector?: string;
+    /** Where this flow returns to: a path on your app. */
+    returnTo?: string;
     /** "Connect your apps" unless set. */
     label?: string;
     /** "Connected" unless set. */

package/dist/vue.cjs.js

@@ -1 +1 @@
-"use strict";var e=require("vue"),t=require("@withone/connect");const n={type:Boolean,default:void 0},o=e.defineComponent({name:"OneConnectButton",props:{authorizeUrl:{type:String,required:!0},logos:{type:Array,default:void 0},platforms:{type:Array,default:void 0},connected:n,disabled:n,variant:{type:String,default:void 0},size:{type:String,default:void 0},fullWidth:n,theme:{type:String,default:void 0},connectTheme:{type:String,default:void 0},label:{type:String,default:void 0},connectedLabel:{type:String,default:void 0},description:{type:String,default:void 0}},emits:{success:()=>!0,error:(e,t)=>"string"==typeof e&&"string"==typeof t,cancel:()=>!0},setup(n,{emit:o}){const r=e.ref(null);let i=null;const l=()=>({...n,onSuccess:()=>o("success"),onError:(e,t)=>o("error",e,t),onCancel:()=>o("cancel")});return e.onMounted(()=>{r.value&&(i=t.renderConnectButton(r.value,l()))}),e.watch(()=>({...n}),()=>{var e;return null===(e=i)||void 0===e?void 0:e.update(l())},{deep:!0}),e.onBeforeUnmount(()=>{var e;null===(e=i)||void 0===e||e.destroy(),i=null}),()=>{var t;return e.h("span",{ref:r,class:"one-connect","data-variant":null!==(t=n.variant)&&void 0!==t?t:"default","data-full-width":n.fullWidth?"":void 0})}}});exports.ConnectButton=o;
+"use strict";var e=require("vue"),t=require("@withone/connect");const n={type:Boolean,default:void 0},o=e.defineComponent({name:"OneConnectButton",props:{authorizeUrl:{type:String,required:!0},logos:{type:Array,default:void 0},platforms:{type:Array,default:void 0},connected:n,disabled:n,variant:{type:String,default:void 0},size:{type:String,default:void 0},fullWidth:n,theme:{type:String,default:void 0},connectTheme:{type:String,default:void 0},connector:{type:String,default:void 0},returnTo:{type:String,default:void 0},label:{type:String,default:void 0},connectedLabel:{type:String,default:void 0},description:{type:String,default:void 0}},emits:{success:()=>!0,error:(e,t)=>"string"==typeof e&&"string"==typeof t,cancel:()=>!0},setup(n,{emit:o}){const r=e.ref(null);let i=null;const d=()=>({...n,onSuccess:()=>o("success"),onError:(e,t)=>o("error",e,t),onCancel:()=>o("cancel")});return e.onMounted(()=>{r.value&&(i=t.renderConnectButton(r.value,d()))}),e.watch(()=>({...n}),()=>{var e;return null===(e=i)||void 0===e?void 0:e.update(d())},{deep:!0}),e.onBeforeUnmount(()=>{var e;null===(e=i)||void 0===e||e.destroy(),i=null}),()=>{var t;return e.h("span",{ref:r,class:"one-connect","data-variant":null!==(t=n.variant)&&void 0!==t?t:"default","data-full-width":n.fullWidth?"":void 0})}}});exports.ConnectButton=o;

package/dist/vue.d.ts

@@ -42,6 +42,14 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
         type: PropType<OneConnectTheme>;
         default: undefined;
     };
+    connector: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    returnTo: {
+        type: StringConstructor;
+        default: undefined;
+    };
     label: {
         type: StringConstructor;
         default: undefined;
@@ -102,6 +110,14 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
         type: PropType<OneConnectTheme>;
         default: undefined;
     };
+    connector: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    returnTo: {
+        type: StringConstructor;
+        default: undefined;
+    };
     label: {
         type: StringConstructor;
         default: undefined;
@@ -123,6 +139,8 @@ export declare const ConnectButton: import("vue").DefineComponent<import("vue").
     label: string;
     disabled: boolean;
     connectTheme: OneConnectTheme;
+    connector: string;
+    returnTo: string;
     logos: ConnectButtonLogoInput[];
     platforms: ConnectButtonLogoInput[];
     variant: ConnectButtonVariant;

package/dist/vue.esm.js

@@ -1 +1 @@
-import{defineComponent as e,ref as t,onMounted as n,watch as o,onBeforeUnmount as r,h as l}from"vue";import{renderConnectButton as i}from"@withone/connect";const a={type:Boolean,default:void 0},d=e({name:"OneConnectButton",props:{authorizeUrl:{type:String,required:!0},logos:{type:Array,default:void 0},platforms:{type:Array,default:void 0},connected:a,disabled:a,variant:{type:String,default:void 0},size:{type:String,default:void 0},fullWidth:a,theme:{type:String,default:void 0},connectTheme:{type:String,default:void 0},label:{type:String,default:void 0},connectedLabel:{type:String,default:void 0},description:{type:String,default:void 0}},emits:{success:()=>!0,error:(e,t)=>"string"==typeof e&&"string"==typeof t,cancel:()=>!0},setup(e,{emit:a}){const d=t(null);let u=null;const c=()=>({...e,onSuccess:()=>a("success"),onError:(e,t)=>a("error",e,t),onCancel:()=>a("cancel")});return n(()=>{d.value&&(u=i(d.value,c()))}),o(()=>({...e}),()=>{var e;return null===(e=u)||void 0===e?void 0:e.update(c())},{deep:!0}),r(()=>{var e;null===(e=u)||void 0===e||e.destroy(),u=null}),()=>{var t;return l("span",{ref:d,class:"one-connect","data-variant":null!==(t=e.variant)&&void 0!==t?t:"default","data-full-width":e.fullWidth?"":void 0})}}});export{d as ConnectButton};
+import{defineComponent as e,ref as t,onMounted as n,watch as o,onBeforeUnmount as r,h as i}from"vue";import{renderConnectButton as l}from"@withone/connect";const d={type:Boolean,default:void 0},a=e({name:"OneConnectButton",props:{authorizeUrl:{type:String,required:!0},logos:{type:Array,default:void 0},platforms:{type:Array,default:void 0},connected:d,disabled:d,variant:{type:String,default:void 0},size:{type:String,default:void 0},fullWidth:d,theme:{type:String,default:void 0},connectTheme:{type:String,default:void 0},connector:{type:String,default:void 0},returnTo:{type:String,default:void 0},label:{type:String,default:void 0},connectedLabel:{type:String,default:void 0},description:{type:String,default:void 0}},emits:{success:()=>!0,error:(e,t)=>"string"==typeof e&&"string"==typeof t,cancel:()=>!0},setup(e,{emit:d}){const a=t(null);let u=null;const c=()=>({...e,onSuccess:()=>d("success"),onError:(e,t)=>d("error",e,t),onCancel:()=>d("cancel")});return n(()=>{a.value&&(u=l(a.value,c()))}),o(()=>({...e}),()=>{var e;return null===(e=u)||void 0===e?void 0:e.update(c())},{deep:!0}),r(()=>{var e;null===(e=u)||void 0===e||e.destroy(),u=null}),()=>{var t;return i("span",{ref:a,class:"one-connect","data-variant":null!==(t=e.variant)&&void 0!==t?t:"default","data-full-width":e.fullWidth?"":void 0})}}});export{a as ConnectButton};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "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

@@ -149,8 +149,10 @@ import { ConnectButton } from "@withone/connect/react";
 
 Optional props: `variant` ("default" | "accent" | "block"), `size` ("sm" |
 "md" | "lg"), `fullWidth`, `theme` ("light" | "dark" | "auto"),
-`connectTheme` ("light" | "dark", One's page), `label`, `connectedLabel`,
-`description`, `disabled`, `onCancel`. The accent variant's colours come
+`connectTheme` ("light" | "dark", One's page), `connector` (a slug such as
+"gmail": One's page opens that connector's connect screen first, then the
+usual list), `returnTo` (a path on the app this flow returns to), `label`,
+`connectedLabel`, `description`, `disabled`, `onCancel`. The accent variant's colours come
 from the host's `--one-connect-accent` and `--one-connect-accent-fg` CSS
 variables.
 
@@ -177,8 +179,15 @@ keep it and wire the flow to it instead of adding a second style:
   button.addEventListener("click", () => flow.open());
   ```
 
+- One connector at a time (a chat that says "Connect Gmail", a settings
+  row): `useOneConnect({ authorizeUrl, connector: "gmail", returnTo: "/chat/42" })`.
+  One's page still signs the user in and asks for the space, then opens
+  Gmail's connect screen instead of the list; the list follows with
+  everything connected. `returnTo` must be a path on the app.
+
 - No SDK in the browser (server-rendered pages): a plain link,
-  `<a href="/api/one/authorize">`. The user returns with
+  `<a href="/api/one/authorize">` (add `#one_connector=gmail` and
+  `?one_return_to=%2Fchat%2F42` for the above). The user returns with
   `?one_connect=success`, or `?one_connect=error&one_connect_error=` with
   `declined`, `expired` or `failed`. Show the app's own text per code, never
   text from the URL, and remove the parameters after reading them.
@@ -205,7 +214,7 @@ const reply = await oneConnect.runAction(userId, {
   encoding: "json",                           // or "form" / "multipart", as the guide says
   headers: {},                                // only when the guide names one
 });
-// { status, ok, blockedByGrant, data }
+// { status, ok, blockedByGrant, refusal, data }
 ```
 
 Each connection's `access` is `{ policy: "full" }`, `{ policy: "methods",
@@ -221,8 +230,18 @@ user's id to every call it makes.
 
 ## 8 - Errors
 
-A `403` reply with `blockedByGrant: true` means the call is outside what
-the user granted. Do not retry it.
+`refusal` says why One itself turned a call down:
+
+- `"grant"` (`403`, `blockedByGrant: true`): outside what the user granted.
+  Do not retry it.
+- `"plan_limit"` (`402`): a plan limit, not the grant. Wait and retry later.
+  Do not ask the user to reconnect.
+- `"rate_limit"` (`429`): too many calls. Wait and retry.
+- `"one_error"` (other, e.g. `5xx`): retry with a backoff.
+- `null`: not One's refusal; the provider's own answer, or a success.
+
+Only a `403` means "outside the grant". Never treat a `402`, `429` or `5xx`
+as a missing permission.
 
 Errors are `OneConnectError` with a `code`. Handle them where the app calls One:
 

package/src/button.ts

@@ -182,6 +182,8 @@ const flowOptions = (
 ): OneConnectFlowOptions => ({
   authorizeUrl: props.authorizeUrl,
   connectTheme: props.connectTheme,
+  connector: props.connector,
+  returnTo: props.returnTo,
   ...handlers,
 });
 
@@ -382,6 +384,8 @@ const ATTRIBUTES = [
   "full-width",
   "theme",
   "connect-theme",
+  "connector",
+  "return-to",
   "label",
   "connected-label",
   "description",
@@ -454,6 +458,8 @@ export function registerConnectButton(): void {
         fullWidth: flag(this, "full-width"),
         theme: attributeAs(this, "theme", ["light", "dark", "auto"]),
         connectTheme: attributeAs(this, "connect-theme", ["light", "dark"]),
+        connector: this.getAttribute("connector") ?? undefined,
+        returnTo: this.getAttribute("return-to") ?? undefined,
         label: this.getAttribute("label") ?? undefined,
         connectedLabel: this.getAttribute("connected-label") ?? undefined,
         description: this.getAttribute("description") ?? undefined,

package/src/constants.ts

@@ -13,6 +13,16 @@ export const LEGACY_MESSAGE_PARAM = "one_connect_message";
  *  chain, so the app's backend forwards nothing. */
 export const THEME_PARAM = "one_theme";
 
+/** Fragment key naming the connector One's page opens first. Sign-in
+ *  and the space step run as always; then that connector's connect
+ *  screen opens instead of the list, and the list follows with
+ *  everything the user has connected. */
+export const CONNECTOR_PARAM = "one_connector";
+
+/** Query param on the app's own authorize route naming where this one
+ *  flow returns to. The route reads it; it never reaches One. */
+export const RETURN_TO_PARAM = "one_return_to";
+
 /** One's connector logos, by slug. */
 export const CONNECTOR_ASSETS_URL = "https://assets.withone.ai/connectors";
 

package/src/flow.ts

@@ -1,4 +1,4 @@
-import { THEME_PARAM } from "./constants";
+import { CONNECTOR_PARAM, RETURN_TO_PARAM, THEME_PARAM } from "./constants";
 import { hasReturnParams, parseReturn, stripReturnParams } from "./return";
 import type {
   OneConnectFlow,
@@ -91,11 +91,19 @@ function bindPageshow(): void {
   });
 }
 
+/** The theme and the connector ride the fragment: no server sees it,
+ *  and it survives every redirect to One's page. The return path is a
+ *  query param for the app's own route, which reads it and keeps it. */
 const authorizeUrlFor = (options: OneConnectFlowOptions): string => {
-  const theme = options.connectTheme;
   try {
     const url = new URL(options.authorizeUrl, window.location.origin);
-    if (theme) url.hash = `${THEME_PARAM}=${theme}`;
+    if (options.returnTo) url.searchParams.set(RETURN_TO_PARAM, options.returnTo);
+    const fragment = new URLSearchParams();
+    if (options.connectTheme) fragment.set(THEME_PARAM, options.connectTheme);
+    const connector = options.connector?.trim().toLowerCase();
+    if (connector) fragment.set(CONNECTOR_PARAM, connector);
+    const hash = fragment.toString();
+    if (hash) url.hash = hash;
     return url.toString();
   } catch {
     return options.authorizeUrl;

package/src/next.ts

@@ -14,6 +14,7 @@
  * That serves /api/one/authorize and /api/one/callback. Register
  * `https://yourapp.com/api/one/callback` as the app's redirect URI.
  */
+import { RETURN_TO_PARAM } from "./constants";
 import type { CompleteAuthorizationResult, OneConnectClient } from "./server";
 
 export interface OneConnectRoutesOptions {
@@ -109,7 +110,11 @@ export function createOneConnectRoutes(
     const user = await requireUser(request);
     if (user instanceof Response) return user;
     const loginHint = (await options.loginHintFor?.(request)) ?? undefined;
-    const { redirectUrl, cookie } = oneConnect.startAuthorization({ loginHint });
+    // The browser flow names where this one flow returns to; the client
+    // keeps only a path on the app, so a crafted link goes nowhere else.
+    const returnTo =
+      new URL(request.url).searchParams.get(RETURN_TO_PARAM) ?? undefined;
+    const { redirectUrl, cookie } = oneConnect.startAuthorization({ loginHint, returnTo });
     return redirectWithCookies(redirectUrl, [
       serializeCookie(cookie.name, cookie.value, cookie.options),
     ]);