@conveo/conveo-sdk 0.4.0 → 0.4.1

package/README.md

@@ -103,6 +103,70 @@ Want a full working example? See the
 [template app](https://github.com/conveo/agentgateway-template-app). Clone
 it and you're done.
 
+## Third-party SDKs through the gateway
+
+`gatewayFetch({ service })` is the low-level way to reach a gateway-fronted vendor
+API. For the common ones, these subpaths hand you the **official vendor SDK** already
+pointed at the gateway and authenticated — no host, no token, no vendor key in your app:
+
+| Import | Returns | Vendor SDK |
+|---|---|---|
+| `@conveo/conveo-sdk/linear` | `getLinearClient()` → `LinearClient` | `@linear/sdk` |
+| `@conveo/conveo-sdk/hubspot` | `getHubspotClient()` → HubSpot `Client` | `@hubspot/api-client` |
+| `@conveo/conveo-sdk/postgrest` | `postgrest()` / `postgrestWithCount()` | none (typed helper) |
+
+**Prerequisites (one-time):**
+
+1. On the Vercel project: **Settings → Functions → OIDC Federation = ON** (Vercel then
+   injects a fresh `VERCEL_OIDC_TOKEN` into every server invocation). Install
+   `@vercel/functions` for automatic token refresh.
+2. The app must be **granted** each route — the gateway is fail-closed. Onboarding adds
+   an `Identity` + `Grant` for your Vercel project in `conveo/agentgateway`; until then,
+   calls return `401`.
+3. Install the vendor SDK you use (optional peer deps): `pnpm add @linear/sdk` /
+   `pnpm add @hubspot/api-client`. PostgREST needs none.
+
+**Linear / HubSpot** — build the client **per request** (the OIDC token rotates) and use
+the native SDK:
+
+```ts
+import { getLinearClient } from "@conveo/conveo-sdk/linear";
+import { getHubspotClient } from "@conveo/conveo-sdk/hubspot";
+
+export async function GET() {
+  const linear = await getLinearClient();
+  const issues = await linear.issues({ first: 10 });
+
+  const hs = await getHubspotClient();
+  const deals = await hs.crm.deals.basicApi.getPage(10);
+
+  return Response.json({ issues: issues.nodes, deals: deals.results });
+}
+```
+
+**PostgREST** — a typed helper returning a result union (never throws on a bad status):
+
+```ts
+import { postgrest } from "@conveo/conveo-sdk/postgrest";
+
+const res = await postgrest<Org[]>("Organization?select=id,name&limit=100");
+if (!res.ok) return Response.json({ error: res.kind }, { status: res.status });
+return Response.json(res.data); // res.kind: ok | unauthenticated | unauthorized | unreachable | error
+```
+
+Notes:
+
+- **Server-side only** — these need the Vercel OIDC token. Never call from a client component.
+- **Call the factory per request**, inside your handler — never cache a client at module scope.
+- **App identity, not user identity** — the gateway injects a *shared* upstream credential
+  (e.g. Linear writes appear as the shared app actor, not the signed-in person).
+- **Hosts** follow the same `service` convention as `gatewayFetch`: `linear`/`hubspot`
+  resolve to `https://<name>.internal.conveo.ai` (override with
+  `AGENTGATEWAY_SERVICE_<NAME>_URL` / `AGENTGATEWAY_SERVICE_DOMAIN`, or a per-call
+  `baseUrl`). PostgREST is a path on the API base (`AGENTGATEWAY_API_URL`).
+- **Errors:** `401` = OIDC off, wrong project slug, or route not granted; `403` = the
+  upstream credential's scopes don't cover the call (a gateway-side change).
+
 ## How it works
 
 ![How it works](docs/how-it-works.svg)
@@ -137,6 +201,9 @@ The SDK is a pure, environment-free core with thin adapters per runtime:
 | `…/vercel` | root `middleware.ts` of any non-Next Vercel app (Vite SPA etc.) |
 | `…/supabase` | `requireGatewayUser(req)` in Deno edge functions |
 | `…/server` | `getGatewayUser()`, `gatewayFetch()` in Next server code |
+| `…/linear` | `getLinearClient()` — Linear via the gateway ([integrations](#third-party-sdks-through-the-gateway)) |
+| `…/hubspot` | `getHubspotClient()` — HubSpot via the gateway |
+| `…/postgrest` | `postgrest()` — Conveo Postgres replica via the gateway |
 
 ### What the middleware verifies
 

package/dist/integrations/_shared.d.ts

@@ -0,0 +1,65 @@
+export interface IntegrationOptions {
+    /**
+     * Override the resolved gateway host (full base URL). Precedence: this >
+     * `AGENTGATEWAY_SERVICE_<NAME>_URL` env > `https://<name>.<domain>` convention.
+     */
+    baseUrl?: string;
+    /**
+     * Supply the bearer token yourself. Escape hatch for non-Vercel runtimes and
+     * tests; by default the app's Vercel OIDC token is fetched fresh per call.
+     */
+    getToken?: () => Promise<string> | string;
+    /**
+     * Inject a `fetch` implementation. Used by the custom-fetch integrations and the
+     * raw helpers (e.g. tests). Ignored by static-token vendor SDKs (Linear, HubSpot)
+     * that take the token at construction and use their own transport.
+     */
+    fetch?: typeof fetch;
+}
+/** Resolve the bearer token: the caller's `getToken`, else the app's Vercel OIDC token. */
+export declare function resolveToken(opts?: IntegrationOptions): Promise<string>;
+/**
+ * A `fetch` that attaches `Authorization: Bearer <token>` — but only to the gateway
+ * origin. Handed to custom-fetch vendor SDKs (e.g. Notion) and used by the raw
+ * helpers. Refuses any other origin so a misconfigured `baseUrl` can't leak the token.
+ */
+export declare function createGatewayFetch(allowedHost: string, opts?: IntegrationOptions): typeof fetch;
+/**
+ * Typed result for the raw (non-vendor-SDK) helpers. Distinguishes a gateway
+ * rejection (401, your OIDC token / grant) from an upstream scope error (403) from
+ * a network failure (`unreachable`) — so callers never fabricate data on failure.
+ */
+export type GatewayResult<T> = {
+    ok: true;
+    kind: "ok";
+    status: number;
+    data: T;
+} | {
+    ok: false;
+    kind: "unauthenticated";
+    status: number;
+    error: string;
+} | {
+    ok: false;
+    kind: "unauthorized";
+    status: number;
+    error: string;
+} | {
+    ok: false;
+    kind: "unreachable";
+    status: 0;
+    error: string;
+} | {
+    ok: false;
+    kind: "error";
+    status: number;
+    error: string;
+};
+/** Map a `Response` to a {@link GatewayResult}. Assumes a JSON body on success. */
+export declare function toGatewayResult<T>(response: Response): Promise<GatewayResult<T>>;
+/**
+ * Fetch a gateway JSON endpoint and map it to a {@link GatewayResult}. A network
+ * failure (`fetch` throwing a `TypeError`) becomes `unreachable`; config/origin/token
+ * errors propagate (they are programmer errors, not request outcomes).
+ */
+export declare function gatewayJson<T>(url: string, init: RequestInit, opts?: IntegrationOptions): Promise<GatewayResult<T>>;

package/dist/integrations/_shared.js

@@ -0,0 +1 @@
+import{getAppToken as c}from"../internal.js";function u(t){return Promise.resolve(t?.getToken?t.getToken():c(process.env))}function f(t,r){const o=r?.fetch??fetch,n=new URL(t).origin;return(async(e,a)=>{const s=e instanceof URL?e:new URL(typeof e=="string"?e:e.url);if(s.origin!==n)throw new Error(`gateway fetch refused: ${s.origin} is not the gateway origin ${n}`);const i=new Headers(a?.headers??(typeof e=="object"&&"headers"in e?e.headers:void 0));return i.set("authorization",`Bearer ${await u(r)}`),o(s,{...a,headers:i})})}async function h(t){try{return await t.text()}catch{return""}}async function d(t){if(t.ok)return{ok:!0,kind:"ok",status:t.status,data:await t.json()};const r=await h(t);return t.status===401?{ok:!1,kind:"unauthenticated",status:401,error:r}:t.status===403?{ok:!1,kind:"unauthorized",status:403,error:r}:{ok:!1,kind:"error",status:t.status,error:r}}async function k(t,r,o){const n=f(t,o);let e;try{e=await n(t,r)}catch(a){if(a instanceof TypeError)return{ok:!1,kind:"unreachable",status:0,error:a.message};throw a}return d(e)}export{f as createGatewayFetch,k as gatewayJson,u as resolveToken,d as toGatewayResult};

package/dist/integrations/hubspot.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HubSpot via the agent gateway, using the official `@hubspot/api-client`.
+ *
+ * The app never holds a HubSpot key: the client's `basePath` is the gateway
+ * (`hubspot.internal.conveo.ai`, paths map 1:1 to `api.hubapi.com`) and its
+ * `accessToken` is the app's Vercel OIDC token; the gateway validates it and swaps
+ * in the shared HubSpot private-app token upstream.
+ *
+ * ```ts
+ * import { getHubspotClient } from "@conveo/conveo-sdk/hubspot";
+ *
+ * export async function GET() {
+ *   const hs = await getHubspotClient();          // build per request — token rotates
+ *   const page = await hs.crm.deals.basicApi.getPage(10);
+ *   return Response.json(page.results);
+ * }
+ * ```
+ *
+ * Static-token bucket: `@hubspot/api-client` has no custom-fetch seam and bakes the
+ * token in at construction, so build a fresh client per request. SERVER-SIDE ONLY.
+ */
+import { Client } from "@hubspot/api-client";
+import { type IntegrationOptions } from "./_shared.js";
+export declare function getHubspotClient(opts?: IntegrationOptions): Promise<Client>;

package/dist/integrations/hubspot.js

@@ -0,0 +1 @@
+import{Client as r}from"@hubspot/api-client";import{resolveServiceUrl as o}from"../internal.js";import{resolveToken as t}from"./_shared.js";async function a(e){return new r({basePath:e?.baseUrl??o("hubspot",process.env),accessToken:await t(e)})}export{a as getHubspotClient};

package/dist/integrations/linear.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Linear via the agent gateway, using the official `@linear/sdk`.
+ *
+ * The app never holds a Linear token: the client is pointed at the gateway
+ * (`linear.internal.conveo.ai/graphql`) and authenticates with the app's Vercel
+ * OIDC token; the gateway validates it and attaches the shared Linear app token
+ * upstream (writes show as the shared app actor, not a person).
+ *
+ * ```ts
+ * import { getLinearClient } from "@conveo/conveo-sdk/linear";
+ *
+ * export async function GET() {
+ *   const linear = await getLinearClient();      // build per request — token rotates
+ *   const issues = await linear.issues({ first: 10 });
+ *   return Response.json(issues.nodes);
+ * }
+ * ```
+ *
+ * Static-token bucket: `@linear/sdk` bakes the token in at construction, so build
+ * a fresh client per request. SERVER-SIDE ONLY (needs the Vercel OIDC token).
+ */
+import { LinearClient } from "@linear/sdk";
+import { type IntegrationOptions } from "./_shared.js";
+export declare function getLinearClient(opts?: IntegrationOptions): Promise<LinearClient>;

package/dist/integrations/linear.js

@@ -0,0 +1 @@
+import{LinearClient as n}from"@linear/sdk";import{resolveServiceUrl as o}from"../internal.js";import{resolveToken as i}from"./_shared.js";async function s(e){const r=e?.baseUrl??`${o("linear",process.env)}/graphql`;return new n({apiUrl:r,accessToken:await i(e)})}export{s as getLinearClient};

package/dist/integrations/postgrest.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PostgREST (the Conveo central Postgres replica) via the agent gateway.
+ *
+ * No vendor SDK — a thin typed helper over the gateway. The app authenticates with
+ * its Vercel OIDC token; the gateway validates it and forwards to PostgREST under
+ * the `/postgrest` mount on the API base (the prefix is stripped before PostgREST
+ * sees it). Table names are PascalCase.
+ *
+ * Unlike Linear/HubSpot (host-based `service` routes), PostgREST is a path under the
+ * API base — so it resolves from `AGENTGATEWAY_API_URL` (default `gateway.ops.conveo.ai`),
+ * matching `gatewayFetch`'s `base: "api"`.
+ *
+ * ```ts
+ * import { postgrest } from "@conveo/conveo-sdk/postgrest";
+ *
+ * const res = await postgrest<Org[]>("Organization?select=id,name&limit=100");
+ * if (!res.ok) return Response.json({ error: res.kind }, { status: res.status });
+ * return Response.json(res.data);
+ * ```
+ */
+import { type GatewayResult, type IntegrationOptions } from "./_shared.js";
+/**
+ * Run a PostgREST query (e.g. `"Organization?select=id,name&limit=100"`). Pass
+ * `init` for writes (`method`, `body`, …).
+ */
+export declare function postgrest<T>(query: string, init?: RequestInit, opts?: IntegrationOptions): Promise<GatewayResult<T>>;
+/**
+ * Run a PostgREST query and also return the exact total row count (sends
+ * `Prefer: count=exact` and parses the `Content-Range` response header). `total`
+ * is `null` if PostgREST didn't return a count.
+ */
+export declare function postgrestWithCount<T>(query: string, init?: RequestInit, opts?: IntegrationOptions): Promise<GatewayResult<{
+    rows: T;
+    total: number | null;
+}>>;

package/dist/integrations/postgrest.js

@@ -0,0 +1 @@
+import{createGatewayFetch as p,gatewayJson as f}from"./_shared.js";const h="https://gateway.ops.conveo.ai";function c(a,r){const e=(r?.baseUrl??`${process.env.AGENTGATEWAY_API_URL??h}/postgrest`).replace(/\/+$/,""),n=a.replace(/^\/?(postgrest\/)?/,"");return`${e}/${n}`}function k(a,r={},e){return f(c(a,e),r,e)}async function g(a,r={},e){const n=c(a,e),i=p(n,e),o=new Headers(r.headers);o.set("prefer","count=exact");let t;try{t=await i(n,{...r,headers:o})}catch(s){if(s instanceof TypeError)return{ok:!1,kind:"unreachable",status:0,error:s.message};throw s}if(!t.ok){const s=await t.text().catch(()=>"");return t.status===401?{ok:!1,kind:"unauthenticated",status:401,error:s}:t.status===403?{ok:!1,kind:"unauthorized",status:403,error:s}:{ok:!1,kind:"error",status:t.status,error:s}}const l=await t.json(),u=Number(t.headers.get("content-range")?.split("/")[1]);return{ok:!0,kind:"ok",status:t.status,data:{rows:l,total:Number.isFinite(u)?u:null}}}export{k as postgrest,g as postgrestWithCount};

package/dist/internal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Internal, runtime-agnostic gateway helpers shared by `./server` and the
+ * third-party integrations (`./linear`, `./hubspot`, `./postgrest`).
+ *
+ * Deliberately free of `next` (and any runtime-specific) imports so the
+ * integration subpaths can reuse the same host/token resolution without dragging
+ * Next.js into a non-Next consumer.
+ */
+/**
+ * Resolve a host-based, gateway-fronted vendor API to its base URL. Honours
+ * `AGENTGATEWAY_SERVICE_<NAME>_URL`, else `https://<name>.<AGENTGATEWAY_SERVICE_DOMAIN
+ * ?? internal.conveo.ai>`.
+ */
+export declare function resolveServiceUrl(service: string, env: NodeJS.ProcessEnv): string;
+/**
+ * The app's own identity token (Vercel OIDC). Prefers `getVercelOidcToken()` from
+ * `@vercel/functions` — it refreshes the short-lived token in dev and reads the
+ * runtime token in prod — but that's an OPTIONAL peer dep, so we fall back to the
+ * raw `VERCEL_OIDC_TOKEN` env var when it isn't installed.
+ */
+export declare function getAppToken(env: NodeJS.ProcessEnv): Promise<string>;

package/dist/internal.js

@@ -0,0 +1 @@
+const n=/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;function a(e,t){if(!n.test(e))throw new Error(`invalid service name "${e}" \u2014 expected a lowercase DNS label (letters, digits, dashes)`);const r=t[`AGENTGATEWAY_SERVICE_${e.toUpperCase().replace(/-/g,"_")}_URL`];if(r)return r;const o=t.AGENTGATEWAY_SERVICE_DOMAIN??"internal.conveo.ai";return`https://${e}.${o}`}async function c(e){try{const{getVercelOidcToken:r}=await import("@vercel/functions/oidc"),o=await r();if(o)return o}catch{}const t=e.VERCEL_OIDC_TOKEN;if(!t)throw new Error("VERCEL_OIDC_TOKEN is not available \u2014 enable OIDC federation on the Vercel project (or `vercel env pull` for local dev). Install @vercel/functions for automatic token refresh.");return t}export{c as getAppToken,a as resolveServiceUrl};

package/dist/server.js

@@ -1 +1 @@
-import{headers as f}from"next/headers";import{configFromEnv as d,isDevelopment as w}from"./adapters/env.js";import{GatewayAuthError as l,IDENTITY_HEADERS as m}from"./core/types.js";import{createVerifier as v}from"./core/verify.js";let E;function A(){return E??=v(d(process.env)),E}async function V(){const e=(await f()).get(m.token);if(!e){const t=process.env.AGENTGATEWAY_DEV_MOCK_USER;if(t&&w(process.env)){const o=t.toLowerCase();return{sub:"dev-mock-user",email:o,emailVerified:!0,token:"",claims:{sub:"dev-mock-user",email:o}}}throw new l("unauthenticated","no gateway user on this request \u2014 public path, optional auth, or middleware not applied")}return A().verifyToken(e)}const g={api:"https://gateway.ops.conveo.ai",mcp:"https://mcp.ops.conveo.ai"},_=/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;function y(r,e){if(!_.test(r))throw new Error(`gatewayFetch: invalid service name "${r}" \u2014 expected a lowercase DNS label (letters, digits, dashes)`);const t=e[`AGENTGATEWAY_SERVICE_${r.toUpperCase().replace(/-/g,"_")}_URL`];if(t)return t;const o=e.AGENTGATEWAY_SERVICE_DOMAIN??"internal.conveo.ai";return`https://${r}.${o}`}async function T(r){try{const{getVercelOidcToken:t}=await import("@vercel/functions/oidc"),o=await t();if(o)return o}catch{}const e=r.VERCEL_OIDC_TOKEN;if(!e)throw new Error("VERCEL_OIDC_TOKEN is not available \u2014 enable OIDC federation on the Vercel project (or `vercel env pull` for local dev). Install @vercel/functions for automatic token refresh.");return e}async function I(r,e={}){const{user:t,identity:o=e.user?"user":"app",base:c,service:u,...h}=e,a=process.env;let n;if(u!==void 0){if(c!==void 0)throw new Error("gatewayFetch: pass either `service` or `base`, not both");n=y(u,a)}else{const p=c??"api";n=(p==="mcp"?a.AGENTGATEWAY_MCP_URL:a.AGENTGATEWAY_API_URL)??g[p]}const i=new URL(r,n.endsWith("/")?n:`${n}/`);if(i.origin!==new URL(n).origin)throw new Error(`gatewayFetch path must stay on the gateway origin (resolved to ${i.origin})`);const s=new Headers(h.headers);if(o==="user"){if(!t?.token)throw new l("unauthenticated",'gatewayFetch with identity "user" needs a verified user with a token (mock users have none)');s.set("authorization",`Bearer ${t.token}`)}else s.set("authorization",`Bearer ${await T(a)}`);return fetch(i,{...h,headers:s})}import{GatewayAuthError as b}from"./core/types.js";export{b as GatewayAuthError,I as gatewayFetch,V as getGatewayUser};
+import{headers as f}from"next/headers";import{configFromEnv as m,isDevelopment as v}from"./adapters/env.js";import{GatewayAuthError as w,IDENTITY_HEADERS as E}from"./core/types.js";import{createVerifier as l}from"./core/verify.js";import{getAppToken as g,resolveServiceUrl as y}from"./internal.js";let d;function A(){return d??=l(m(process.env)),d}async function F(){const t=(await f()).get(E.token);if(!t){const r=process.env.AGENTGATEWAY_DEV_MOCK_USER;if(r&&v(process.env)){const o=r.toLowerCase();return{sub:"dev-mock-user",email:o,emailVerified:!0,token:"",claims:{sub:"dev-mock-user",email:o}}}throw new w("unauthenticated","no gateway user on this request \u2014 public path, optional auth, or middleware not applied")}return A().verifyToken(t)}const k={api:"https://gateway.ops.conveo.ai",mcp:"https://mcp.ops.conveo.ai"};async function L(s,t={}){const{user:r,identity:o=t.user?"user":"app",base:c,service:u,...h}=t,n=process.env;let e;if(u!==void 0){if(c!==void 0)throw new Error("gatewayFetch: pass either `service` or `base`, not both");e=y(u,n)}else{const p=c??"api";e=(p==="mcp"?n.AGENTGATEWAY_MCP_URL:n.AGENTGATEWAY_API_URL)??k[p]}const i=new URL(s,e.endsWith("/")?e:`${e}/`);if(i.origin!==new URL(e).origin)throw new Error(`gatewayFetch path must stay on the gateway origin (resolved to ${i.origin})`);const a=new Headers(h.headers);if(o==="user"){if(!r?.token)throw new w("unauthenticated",'gatewayFetch with identity "user" needs a verified user with a token (mock users have none)');a.set("authorization",`Bearer ${r.token}`)}else a.set("authorization",`Bearer ${await g(n)}`);return fetch(i,{...h,headers:a})}import{GatewayAuthError as H}from"./core/types.js";export{H as GatewayAuthError,L as gatewayFetch,F as getGatewayUser};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conveo/conveo-sdk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "SDK for Conveo apps behind the agent gateway: drop-in auth middleware (Next.js / Vercel / Supabase), server helpers, and a dev-token CLI.",
   "license": "UNLICENSED",
   "type": "module",
@@ -39,6 +39,18 @@
     "./server": {
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
+    },
+    "./linear": {
+      "types": "./dist/integrations/linear.d.ts",
+      "default": "./dist/integrations/linear.js"
+    },
+    "./hubspot": {
+      "types": "./dist/integrations/hubspot.d.ts",
+      "default": "./dist/integrations/hubspot.js"
+    },
+    "./postgrest": {
+      "types": "./dist/integrations/postgrest.d.ts",
+      "default": "./dist/integrations/postgrest.js"
     }
   },
   "bin": {
@@ -56,10 +68,18 @@
     "jose": "^6.2.3"
   },
   "peerDependencies": {
+    "@hubspot/api-client": ">=10",
+    "@linear/sdk": ">=30",
     "@vercel/functions": ">=2",
     "next": ">=14"
   },
   "peerDependenciesMeta": {
+    "@hubspot/api-client": {
+      "optional": true
+    },
+    "@linear/sdk": {
+      "optional": true
+    },
     "@vercel/functions": {
       "optional": true
     },
@@ -68,6 +88,8 @@
     }
   },
   "devDependencies": {
+    "@hubspot/api-client": "^14.0.0",
+    "@linear/sdk": "^87.0.0",
     "@types/node": "^24.0.0",
     "@vercel/functions": "^3.7.1",
     "esbuild": "^0.28.1",