@hubspot/app-connect-sdk 1.0.0-alpha.2 → 1.0.0-alpha.21

package/src/server/api-client-core/apis/webhooks.generated.ts

@@ -1,18 +1,18 @@
 import { op } from '../op.ts';
-import type { Webhooks } from './webhooks-types.generated.ts';
+import type { WebhooksWebhooks } from './webhooks-types.generated.ts';
 
 // DO NOT MODIFY - This code was generated by @hubspot/api-client-next-generator
 
 export * from './webhooks-types.generated.ts';
 
-const advanced: Webhooks.AdvancedAPI = {
+export const webhooksWebhooks: WebhooksWebhooks.API = {
+  createBatchEventSubscriptions: (input) =>
+    op.post('/webhooks/2026-03/{appId}/subscriptions/batch/update', {
+      pathParams: { appId: input.appId },
+      body: input.data,
+    }),
   createCrmSnapshots: (input) =>
     op.post('/webhooks-journal/snapshots/2026-03/crm', { body: input }),
-  createSubscriptionFilter: (input) =>
-    op.post('/webhooks-journal/subscriptions/2026-03/filters', { body: input }),
-};
-
-const basic: Webhooks.BasicAPI = {
   createEventSubscription: (input) =>
     op.post('/webhooks/2026-03/{appId}/subscriptions', {
       pathParams: { appId: input.appId },
@@ -20,6 +20,8 @@ const basic: Webhooks.BasicAPI = {
     }),
   createJournalSubscription: (input) =>
     op.post('/webhooks-journal/subscriptions/2026-03', { body: input }),
+  createSubscriptionFilter: (input) =>
+    op.post('/webhooks-journal/subscriptions/2026-03/filters', { body: input }),
   deleteEventSubscription: (input) =>
     op.del('/webhooks/2026-03/{appId}/subscriptions/{subscriptionId}', {
       pathParams: { appId: input.appId, subscriptionId: input.subscriptionId },
@@ -40,10 +42,20 @@ const basic: Webhooks.BasicAPI = {
     op.del('/webhooks-journal/subscriptions/2026-03/filters/{filterId}', {
       pathParams: { filterId: input.filterId },
     }),
+  getEarliestJournalBatch: (input) =>
+    op.get('/webhooks-journal/journal/2026-03/batch/earliest/{count}', {
+      pathParams: { count: input.count },
+      queryParams: { installPortalId: input.installPortalId },
+    }),
   getEarliestJournalEntry: (input) =>
     op.get('/webhooks-journal/journal/2026-03/earliest', {
       queryParams: { installPortalId: input?.installPortalId },
     }),
+  getEarliestLocalJournalBatch: (input) =>
+    op.get('/webhooks-journal/journal-local/2026-03/batch/earliest/{count}', {
+      pathParams: { count: input.count },
+      queryParams: { installPortalId: input.installPortalId },
+    }),
   getEarliestLocalJournalEntry: (input) =>
     op.get('/webhooks-journal/journal-local/2026-03/earliest', {
       queryParams: { installPortalId: input?.installPortalId },
@@ -52,6 +64,16 @@ const basic: Webhooks.BasicAPI = {
     op.get('/webhooks/2026-03/{appId}/subscriptions/{subscriptionId}', {
       pathParams: { appId: input.appId, subscriptionId: input.subscriptionId },
     }),
+  getJournalBatchByRequest: (input) =>
+    op.post('/webhooks-journal/journal/2026-03/batch/read', {
+      queryParams: { installPortalId: input.installPortalId },
+      body: input.data,
+    }),
+  getJournalBatchFromOffset: (input) =>
+    op.get('/webhooks-journal/journal/2026-03/batch/{offset}/next/{count}', {
+      pathParams: { count: input.count, offset: input.offset },
+      queryParams: { installPortalId: input.installPortalId },
+    }),
   getJournalStatus: (input) =>
     op.get('/webhooks-journal/journal/2026-03/status/{statusId}', {
       pathParams: { statusId: input.statusId },
@@ -60,14 +82,37 @@ const basic: Webhooks.BasicAPI = {
     op.get('/webhooks-journal/subscriptions/2026-03/{subscriptionId}', {
       pathParams: { subscriptionId: input.subscriptionId },
     }),
+  getLatestJournalBatch: (input) =>
+    op.get('/webhooks-journal/journal/2026-03/batch/latest/{count}', {
+      pathParams: { count: input.count },
+      queryParams: { installPortalId: input.installPortalId },
+    }),
   getLatestJournalEntry: (input) =>
     op.get('/webhooks-journal/journal/2026-03/latest', {
       queryParams: { installPortalId: input?.installPortalId },
     }),
+  getLatestLocalJournalBatch: (input) =>
+    op.get('/webhooks-journal/journal-local/2026-03/batch/latest/{count}', {
+      pathParams: { count: input.count },
+      queryParams: { installPortalId: input.installPortalId },
+    }),
   getLatestLocalJournalEntry: (input) =>
     op.get('/webhooks-journal/journal-local/2026-03/latest', {
       queryParams: { installPortalId: input?.installPortalId },
     }),
+  getLocalJournalBatchByRequest: (input) =>
+    op.post('/webhooks-journal/journal-local/2026-03/batch/read', {
+      queryParams: { installPortalId: input.installPortalId },
+      body: input.data,
+    }),
+  getLocalJournalBatchFromOffset: (input) =>
+    op.get(
+      '/webhooks-journal/journal-local/2026-03/batch/{offset}/next/{count}',
+      {
+        pathParams: { count: input.count, offset: input.offset },
+        queryParams: { installPortalId: input.installPortalId },
+      }
+    ),
   getLocalJournalStatus: (input) =>
     op.get('/webhooks-journal/journal-local/2026-03/status/{statusId}', {
       pathParams: { statusId: input.statusId },
@@ -112,60 +157,3 @@ const basic: Webhooks.BasicAPI = {
       body: input.data,
     }),
 };
-
-const batch: Webhooks.BatchAPI = {
-  createBatchEventSubscriptions: (input) =>
-    op.post('/webhooks/2026-03/{appId}/subscriptions/batch/update', {
-      pathParams: { appId: input.appId },
-      body: input.data,
-    }),
-  getEarliestJournalBatch: (input) =>
-    op.get('/webhooks-journal/journal/2026-03/batch/earliest/{count}', {
-      pathParams: { count: input.count },
-      queryParams: { installPortalId: input.installPortalId },
-    }),
-  getEarliestLocalJournalBatch: (input) =>
-    op.get('/webhooks-journal/journal-local/2026-03/batch/earliest/{count}', {
-      pathParams: { count: input.count },
-      queryParams: { installPortalId: input.installPortalId },
-    }),
-  getJournalBatchByRequest: (input) =>
-    op.post('/webhooks-journal/journal/2026-03/batch/read', {
-      queryParams: { installPortalId: input.installPortalId },
-      body: input.data,
-    }),
-  getJournalBatchFromOffset: (input) =>
-    op.get('/webhooks-journal/journal/2026-03/batch/{offset}/next/{count}', {
-      pathParams: { count: input.count, offset: input.offset },
-      queryParams: { installPortalId: input.installPortalId },
-    }),
-  getLatestJournalBatch: (input) =>
-    op.get('/webhooks-journal/journal/2026-03/batch/latest/{count}', {
-      pathParams: { count: input.count },
-      queryParams: { installPortalId: input.installPortalId },
-    }),
-  getLatestLocalJournalBatch: (input) =>
-    op.get('/webhooks-journal/journal-local/2026-03/batch/latest/{count}', {
-      pathParams: { count: input.count },
-      queryParams: { installPortalId: input.installPortalId },
-    }),
-  getLocalJournalBatchByRequest: (input) =>
-    op.post('/webhooks-journal/journal-local/2026-03/batch/read', {
-      queryParams: { installPortalId: input.installPortalId },
-      body: input.data,
-    }),
-  getLocalJournalBatchFromOffset: (input) =>
-    op.get(
-      '/webhooks-journal/journal-local/2026-03/batch/{offset}/next/{count}',
-      {
-        pathParams: { count: input.count, offset: input.offset },
-        queryParams: { installPortalId: input.installPortalId },
-      }
-    ),
-};
-
-export const webhooks: Webhooks.API = {
-  advanced: advanced,
-  basic: basic,
-  batch: batch,
-};

package/src/server/api-client-core/client.ts

@@ -18,7 +18,11 @@ import type {
  */
 function assertSuccess(response: ApiResponse): void {
   if (response.status < 200 || response.status >= 300) {
-    throw new HubSpotApiError(response);
+    const error = new HubSpotApiError(response);
+    if (response.bodyJson == null) {
+      error.message = `${error.message} (empty or non-JSON response body)`;
+    }
+    throw error;
   }
 }
 

package/src/server/api-client-core/pagination.ts

@@ -31,7 +31,7 @@ export const pagination = {
    * @example
    * ```ts
    * const allContacts = await client.send(
-   *   pagination.getAll(crmContacts.basic.getContacts()),
+   *   pagination.getAll(crmObjectsContacts.list()),
    * );
    * ```
    */
@@ -78,7 +78,7 @@ export const pagination = {
    * @example
    * ```ts
    * for await (const contact of client.send(
-   *   pagination.getAllStream(crmContacts.basic.getContacts()),
+   *   pagination.getAllStream(crmObjectsContacts.list()),
    * )) {
    *   console.log(contact.id);
    * }

package/src/server/api-client-core/plugins/fetch-transport.ts

@@ -1,10 +1,23 @@
 import { isBinaryData } from '../binary-data.ts';
-import type { Plugin } from '../types.ts';
+import type { Operation, Plugin } from '../types.ts';
 
-const BASE_URL = 'https://api.hubapi.com';
+const HUBSPOT_API_ENDPOINT = 'https://api.hubapi.com';
+
+export interface FetchTransportHeaderContext {
+  /** Fully resolved request URL (endpoint + path + query). */
+  targetUrl: string;
+  /** Uppercase HTTP method. */
+  method: string;
+  /** The operation being sent. */
+  operation: Operation;
+}
 
 export interface FetchTransportPluginOptions {
-  getAccessToken: () => string;
+  getEndpoint?: () => string;
+  getAccessToken?: () => string;
+  getAuthorizationHeaders?: (
+    ctx: FetchTransportHeaderContext
+  ) => Record<string, string> | Promise<Record<string, string>>;
 }
 
 function appendRecordToUrlSearchParams(
@@ -23,6 +36,28 @@ function appendRecordToUrlSearchParams(
   }
 }
 
+async function readResponseBodyJson(response: Response): Promise<unknown> {
+  if (response.status === 204) {
+    return undefined;
+  }
+
+  const text = await response.text();
+  if (text.length === 0) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    if (response.status >= 200 && response.status < 300) {
+      throw new SyntaxError(
+        `fetchTransportPlugin: response body is not valid JSON (status ${response.status})`
+      );
+    }
+    return null;
+  }
+}
+
 /**
  * Transport plugin that executes HTTP requests using the Fetch API.
  *
@@ -38,12 +73,17 @@ export function fetchTransportPlugin(
     activate(api) {
       api.addMiddleware(async (ctx) => {
         const { operation } = ctx;
+        const endpoint = options.getEndpoint?.() ?? HUBSPOT_API_ENDPOINT;
+        const method = operation.method.toUpperCase();
 
         // Interpolate path parameters (e.g. "/contacts/{contactId}" → "/contacts/123")
-        let url = `${BASE_URL}${operation.path}`;
+        let targetUrl = `${endpoint}${operation.path}`;
         if (operation.pathParams) {
           for (const [key, value] of Object.entries(operation.pathParams)) {
-            url = url.replace(`{${key}}`, encodeURIComponent(String(value)));
+            targetUrl = targetUrl.replace(
+              `{${key}}`,
+              encodeURIComponent(String(value))
+            );
           }
         }
 
@@ -52,16 +92,30 @@ export function fetchTransportPlugin(
           const params = new URLSearchParams();
           appendRecordToUrlSearchParams(params, operation.queryParams);
           const qs = params.toString();
-          if (qs) url += `?${qs}`;
+          if (qs) targetUrl += `?${qs}`;
         }
 
+        const authHeaders = options.getAuthorizationHeaders
+          ? await options.getAuthorizationHeaders({
+              targetUrl,
+              method,
+              operation,
+            })
+          : options.getAccessToken
+            ? { Authorization: `Bearer ${options.getAccessToken()}` }
+            : (() => {
+                throw new Error(
+                  'fetchTransportPlugin: getAccessToken or getAuthorizationHeaders is required'
+                );
+              })();
+
         const headers: Record<string, string> = {
           ...(operation.headers ?? {}),
-          Authorization: `Bearer ${options.getAccessToken()}`,
+          ...authHeaders,
         };
 
         const init: RequestInit = {
-          method: operation.method.toUpperCase(),
+          method,
           headers,
         };
 
@@ -100,14 +154,18 @@ export function fetchTransportPlugin(
             init.body = JSON.stringify(operation.body);
           }
         }
-        const response = await fetch(url, init);
+
+        const response = await fetch(targetUrl, init);
+        const responseHeaders: Record<string, string> = Object.create(null);
+        response.headers.forEach((value, key) => {
+          responseHeaders[key] = value;
+        });
 
         return {
           status: response.status,
           statusText: response.statusText,
-          headers: Object.fromEntries(response.headers.entries()),
-          // 204 No Content responses have no body to parse
-          bodyJson: response.status === 204 ? undefined : await response.json(),
+          headers: responseHeaders,
+          bodyJson: await readResponseBodyJson(response),
         };
       });
     },

package/src/server/api-client-core/types.ts

@@ -2,7 +2,7 @@
  * Describes an HTTP operation to be sent through the client middleware pipeline.
  *
  * @typeParam TOutput - The expected response body type. Used via the phantom
- *   `_outputType` field so {@link HubSpotClient["send"]} can infer the return type.
+ *   `_outputType` field so {@link HubSpotClient.send} can infer the return type.
  */
 export interface Operation<TOutput = unknown> {
   /** HTTP method for the request. */

package/src/server/constants.ts

@@ -12,6 +12,25 @@ export const HUBSPOT_ACCESS_TOKEN_COOKIE_NAME = '__Host-hs_access_token';
  */
 export const HUBSPOT_APP_SID_COOKIE_NAME = '__Host-hs_app_sid';
 
+/**
+ * Cookie pinning the browser-facing app origin (e.g.
+ * `https://app.example.com`) for the lifetime of an app session.
+ * Set by `auth/init-session` from the request's `Origin` header and
+ * read by:
+ *
+ * - The CORS middleware to emit a credentialed
+ *   `Access-Control-Allow-Origin` value (`*` is forbidden when
+ *   `Access-Control-Allow-Credentials: true`).
+ * - `auth/complete` to rebuild the OAuth `redirect_uri` it sent to
+ *   HubSpot during `init-session` (the token endpoint validates that
+ *   the two values match).
+ *
+ * `__Host-` prefixed (Path=/, Secure, no Domain), so the same
+ * function host can serve both `hubspot-connect` and `api` routes
+ * and read the cookie from either.
+ */
+export const HUBSPOT_APP_ORIGIN_COOKIE_NAME = '__Host-hs_app_origin';
+
 /**
  * Prefix used for refresh-token cookies. Each session gets its own
  * cookie name (`hs_refresh_<sidHash>`) so multiple devices/tabs can
@@ -22,6 +41,7 @@ export const HUBSPOT_REFRESH_COOKIE_PREFIX = 'hs_refresh_';
 const PROTECTED_COOKIE_NAMES = new Set([
   HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
   HUBSPOT_APP_SID_COOKIE_NAME,
+  HUBSPOT_APP_ORIGIN_COOKIE_NAME,
 ]);
 
 /**
@@ -40,14 +60,19 @@ export function isProtectedCookieName(cookieName: string): boolean {
 
 /**
  * Cookie carrying the PKCE code verifier between `init-session` and
- * `callback`. `Lax` SameSite so it accompanies the redirect back from
- * HubSpot.
+ * `auth/complete`. Set with `SameSite=None; Secure; Partitioned` so the
+ * frontend's credentialed cross-site `POST /auth/complete` (made from
+ * the OAuth callback page on the app origin to the SDK's edge function
+ * origin) carries it through. `Lax` would silently drop it on that
+ * fetch, breaking every successful HubSpot redirect.
  */
 export const TEMP_COOKIE_PKCE_VERIFIER = '__hs_pkce_verifier';
 
 /**
  * Cookie carrying the OAuth `state` value between `init-session` and
- * `callback`. Compared against the `state` query parameter as the
- * primary CSRF defense.
+ * `auth/complete`. Compared against the `state` query parameter as the
+ * primary CSRF defense. Same `SameSite=None; Secure; Partitioned`
+ * attributes as `TEMP_COOKIE_PKCE_VERIFIER` for the same cross-site
+ * `POST /auth/complete` reason.
  */
 export const TEMP_COOKIE_OAUTH_STATE = '__hs_oauth_state';

package/src/server/hono/hono-request-handler.ts

@@ -1,17 +1,22 @@
 import { Hono } from 'hono';
 
-import { noopLogger, type Logger } from '../../shared/logger.ts';
+import { type Logger } from '../../shared/logger.ts';
 import { createHubSpotClient } from '../api-client-core/client.ts';
 import { fetchTransportPlugin } from '../api-client-core/plugins/fetch-transport.ts';
 import {
   HUBSPOT_ACCESS_TOKEN_COOKIE_NAME,
   HUBSPOT_APP_SID_COOKIE_NAME,
 } from '../constants.ts';
-import { createHubSpotProxy } from '../proxy.ts';
 import { sanitizeRequest } from '../sanitize-request.ts';
-import type { AppKeys, UserCredentials } from '../types.ts';
+import type { AppKeys } from '../types.ts';
 import { parseCookies } from '../utils/cookie-utils.ts';
+import {
+  getHubSpotApiOrigin,
+  isHubspotDpopEnabled,
+} from '../utils/env-utils.ts';
+import { buildHubSpotDpopAuthHeaders } from '../utils/hubspot-dpop-auth-headers.ts';
 import type { AppConnectHonoBindings, AppConnectHonoEnv } from './types.ts';
+import { corsMiddleware } from './utils/cors-middleware.ts';
 
 /**
  * Web-standard fetch handler signature returned by
@@ -53,52 +58,88 @@ export interface CreateAppConnectRequestHandlerOptions {
  *
  * - Strips SDK-managed cookies (access token, refresh, sid) from the
  *   request before the app sees them, via `sanitizeRequest`.
- * - Exposes a `hubSpotProxy` on the Hono context so route handlers
+ * - Exposes a `hubSpot.client` on the Hono context so route handlers
  *   can issue authenticated calls to HubSpot's API on behalf of the
  *   browser session.
  */
 export function createAppConnectRequestHandler(
   options: CreateAppConnectRequestHandlerOptions
 ): AppConnectFetchHandler {
-  const { registerRoutes, appKeys, logger = noopLogger } = options;
+  const { registerRoutes, appKeys } = options;
+
+  if (isHubspotDpopEnabled() && appKeys === null) {
+    throw new Error(
+      'createAppConnectRequestHandler: appKeys is required when HUBSPOT_DPOP_ENABLED is true'
+    );
+  }
+
   const app = new Hono<AppConnectHonoEnv>();
+  // Credentialed CORS first: preflights short-circuit with 204
+  // before the auth check runs, and 401 responses still carry
+  // `Access-Control-Allow-*` headers (the browser drops responses
+  // without them on credentialed cross-site fetches).
+  app.use('*', corsMiddleware());
+
+  // Auth gate: every non-OPTIONS request must arrive with the
+  // SDK-managed access-token + session-id cookies. The CORS
+  // middleware above short-circuits OPTIONS, so this only runs on
+  // real requests; missing cookies now surface as a normal 401 with
+  // CORS headers attached on the way back out (the previous
+  // implementation threw on a missing `Cookie` header before any
+  // middleware ran, which broke browser preflights).
+  app.use('*', async (c, next) => {
+    const { authenticated } = c.env.hubSpot;
+    if (!authenticated) {
+      return c.json({ error: 'Unauthorized' }, 401);
+    }
+
+    await next();
+    return;
+  });
+
   registerRoutes(app);
 
   return (request: Request) => {
     const cookie = request.headers.get('Cookie');
-    if (!cookie) {
+    if (!cookie && request.method !== 'OPTIONS') {
       throw new Error('Missing auth cookies');
     }
-    const cookies = parseCookies(cookie);
+    const cookies = parseCookies(cookie ?? '');
     const accessToken = cookies[HUBSPOT_ACCESS_TOKEN_COOKIE_NAME];
     const sessionId = cookies[HUBSPOT_APP_SID_COOKIE_NAME];
-    if (!accessToken || !sessionId) {
-      // Return 401 Unauthorized
-      return new Response(null, {
-        status: 401,
-        statusText: 'Unauthorized',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-      });
-    }
-    const userCredentials: UserCredentials = { accessToken, sessionId };
 
-    const hubSpotProxy = createHubSpotProxy({
-      userCredentials,
-      appKeys,
-      logger,
-    });
+    const client = createHubSpotClient({
+      plugins: [
+        fetchTransportPlugin({
+          getEndpoint: () => {
+            return getHubSpotApiOrigin();
+          },
+          getAuthorizationHeaders: (ctx) => {
+            if (isHubspotDpopEnabled()) {
+              return buildHubSpotDpopAuthHeaders({
+                accessToken: accessToken!,
+                sessionId: sessionId!,
+                appKeys: appKeys!,
+                method: ctx.method,
+                targetUrl: ctx.targetUrl,
+              });
+            }
 
-    const hubSpotClient = createHubSpotClient({
-      plugins: [fetchTransportPlugin({ getAccessToken: () => accessToken })],
+            return {
+              Authorization: `Bearer ${accessToken!}`,
+            };
+          },
+        }),
+      ],
     });
 
     const sanitizedRequest = sanitizeRequest(request);
 
     const honoBindings: AppConnectHonoBindings = {
-      hubSpotProxy,
-      hubSpotClient,
+      hubSpot: {
+        client,
+        authenticated: Boolean(accessToken && sessionId),
+      },
     };
 
     return app.fetch(sanitizedRequest, honoBindings);