@hubspot/app-connect-sdk 1.0.0-alpha.1

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

@@ -0,0 +1,171 @@
+import { op } from '../op.ts';
+import type { Webhooks } 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 = {
+  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 },
+      body: input.data,
+    }),
+  createJournalSubscription: (input) =>
+    op.post('/webhooks-journal/subscriptions/2026-03', { body: input }),
+  deleteEventSubscription: (input) =>
+    op.del('/webhooks/2026-03/{appId}/subscriptions/{subscriptionId}', {
+      pathParams: { appId: input.appId, subscriptionId: input.subscriptionId },
+    }),
+  deleteJournalSubscription: (input) =>
+    op.del('/webhooks-journal/subscriptions/2026-03/{subscriptionId}', {
+      pathParams: { subscriptionId: input.subscriptionId },
+    }),
+  deleteJournalSubscriptionForPortal: (input) =>
+    op.del('/webhooks-journal/subscriptions/2026-03/portals/{portalId}', {
+      pathParams: { portalId: input.portalId },
+    }),
+  deleteSettings: (input) =>
+    op.del('/webhooks/2026-03/{appId}/settings', {
+      pathParams: { appId: input.appId },
+    }),
+  deleteSubscriptionFilter: (input) =>
+    op.del('/webhooks-journal/subscriptions/2026-03/filters/{filterId}', {
+      pathParams: { filterId: input.filterId },
+    }),
+  getEarliestJournalEntry: (input) =>
+    op.get('/webhooks-journal/journal/2026-03/earliest', {
+      queryParams: { installPortalId: input?.installPortalId },
+    }),
+  getEarliestLocalJournalEntry: (input) =>
+    op.get('/webhooks-journal/journal-local/2026-03/earliest', {
+      queryParams: { installPortalId: input?.installPortalId },
+    }),
+  getEventSubscription: (input) =>
+    op.get('/webhooks/2026-03/{appId}/subscriptions/{subscriptionId}', {
+      pathParams: { appId: input.appId, subscriptionId: input.subscriptionId },
+    }),
+  getJournalStatus: (input) =>
+    op.get('/webhooks-journal/journal/2026-03/status/{statusId}', {
+      pathParams: { statusId: input.statusId },
+    }),
+  getJournalSubscription: (input) =>
+    op.get('/webhooks-journal/subscriptions/2026-03/{subscriptionId}', {
+      pathParams: { subscriptionId: input.subscriptionId },
+    }),
+  getLatestJournalEntry: (input) =>
+    op.get('/webhooks-journal/journal/2026-03/latest', {
+      queryParams: { installPortalId: input?.installPortalId },
+    }),
+  getLatestLocalJournalEntry: (input) =>
+    op.get('/webhooks-journal/journal-local/2026-03/latest', {
+      queryParams: { installPortalId: input?.installPortalId },
+    }),
+  getLocalJournalStatus: (input) =>
+    op.get('/webhooks-journal/journal-local/2026-03/status/{statusId}', {
+      pathParams: { statusId: input.statusId },
+    }),
+  getNextJournalEntries: (input) =>
+    op.get('/webhooks-journal/journal/2026-03/offset/{offset}/next', {
+      pathParams: { offset: input.offset },
+      queryParams: { installPortalId: input.installPortalId },
+    }),
+  getNextLocalJournalEntries: (input) =>
+    op.get('/webhooks-journal/journal-local/2026-03/offset/{offset}/next', {
+      pathParams: { offset: input.offset },
+      queryParams: { installPortalId: input.installPortalId },
+    }),
+  getSettings: (input) =>
+    op.get('/webhooks/2026-03/{appId}/settings', {
+      pathParams: { appId: input.appId },
+    }),
+  getSubscriptionFilter: (input) =>
+    op.get('/webhooks-journal/subscriptions/2026-03/filters/{filterId}', {
+      pathParams: { filterId: input.filterId },
+    }),
+  listEventSubscriptions: (input) =>
+    op.get('/webhooks/2026-03/{appId}/subscriptions', {
+      pathParams: { appId: input.appId },
+    }),
+  listJournalSubscriptions: () =>
+    op.get('/webhooks-journal/subscriptions/2026-03'),
+  listSubscriptionFilters: (input) =>
+    op.get(
+      '/webhooks-journal/subscriptions/2026-03/filters/subscription/{subscriptionId}',
+      { pathParams: { subscriptionId: input.subscriptionId } }
+    ),
+  updateEventSubscription: (input) =>
+    op.patch('/webhooks/2026-03/{appId}/subscriptions/{subscriptionId}', {
+      pathParams: { appId: input.appId, subscriptionId: input.subscriptionId },
+      body: input.data,
+    }),
+  updateSettings: (input) =>
+    op.put('/webhooks/2026-03/{appId}/settings', {
+      pathParams: { appId: input.appId },
+      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/binary-data.ts

@@ -0,0 +1,38 @@
+/** Branded symbol used to distinguish {@link BinaryData} from plain objects at runtime. */
+const binaryDataSymbol: unique symbol = Symbol('BinaryData');
+
+/**
+ * A branded wrapper around a binary source (e.g. `Blob`, `File`, `Buffer`)
+ * used to identify file-upload fields in multipart/form-data operations.
+ *
+ * The transport plugin inspects this brand to decide whether a field should
+ * be appended to `FormData` as a `Blob` rather than a stringified value.
+ */
+export interface BinaryData {
+  readonly [binaryDataSymbol]: true;
+  /** The underlying binary source (typically a `Blob` or `File`). */
+  readonly source: unknown;
+}
+
+/**
+ * Wraps a binary source in a {@link BinaryData} branded object so the
+ * transport layer can identify it as a file-upload field.
+ *
+ * @param source - The binary payload (e.g. a `Blob`, `File`, or `Buffer`).
+ * @returns A branded {@link BinaryData} instance.
+ */
+export function createBinaryData(source: unknown): BinaryData {
+  return { [binaryDataSymbol]: true, source } as BinaryData;
+}
+
+/**
+ * Type guard that checks whether a value is a {@link BinaryData} instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is a branded `BinaryData` object.
+ */
+export function isBinaryData(value: unknown): value is BinaryData {
+  return (
+    typeof value === 'object' && value !== null && binaryDataSymbol in value
+  );
+}

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

@@ -0,0 +1,115 @@
+import { HubSpotApiError } from './errors.ts';
+import type {
+  ApiResponse,
+  CreateHubSpotClientOptions,
+  HubSpotApiResponse,
+  HubSpotClient,
+  Middleware,
+  MiddlewareContext,
+  Operation,
+  PluginAPI,
+} from './types.ts';
+
+/**
+ * Throws a {@link HubSpotApiError} if the response status is outside the 2xx range.
+ *
+ * @param response - The raw API response to validate.
+ * @throws {HubSpotApiError} When `response.status` is not between 200 and 299.
+ */
+function assertSuccess(response: ApiResponse): void {
+  if (response.status < 200 || response.status >= 300) {
+    throw new HubSpotApiError(response);
+  }
+}
+
+/**
+ * Composes an array of {@link Middleware} functions into a single dispatch
+ * chain (Koa-style). Each middleware receives a `next` callback that
+ * invokes the subsequent middleware; the final middleware must produce the
+ * response (typically the transport plugin).
+ *
+ * Guards against `next()` being called more than once per middleware and
+ * against pipelines with no terminal handler.
+ *
+ * @param middleware - Ordered list of middleware to compose.
+ * @returns A function that dispatches a {@link MiddlewareContext} through the chain.
+ */
+function compose(
+  middleware: Middleware[]
+): (ctx: MiddlewareContext) => Promise<ApiResponse> {
+  return function (ctx) {
+    let index = -1;
+    function dispatch(i: number): Promise<ApiResponse> {
+      if (i <= index) {
+        return Promise.reject(new Error('next() called multiple times'));
+      }
+      index = i;
+      if (i >= middleware.length) {
+        return Promise.reject(
+          new Error(
+            'No middleware handled the request. Did you forget a transport plugin?'
+          )
+        );
+      }
+      const fn = middleware[i]!;
+      return Promise.resolve(fn(ctx, () => dispatch(i + 1)));
+    }
+    return dispatch(0);
+  };
+}
+
+/**
+ * Creates a {@link HubSpotClient} by activating the provided plugins and
+ * composing their middleware into a single request pipeline.
+ *
+ * @param options - Client configuration including the list of plugins to activate.
+ * @returns A ready-to-use client whose `send` method executes operations through the pipeline.
+ */
+export function createHubSpotClient(
+  options: CreateHubSpotClientOptions
+): HubSpotClient {
+  const middlewareStack: Middleware[] = [];
+
+  const pluginApi: PluginAPI = {
+    addMiddleware(middleware) {
+      middlewareStack.push(middleware);
+    },
+  };
+
+  for (const plugin of options.plugins) {
+    plugin.activate(pluginApi);
+  }
+
+  const run = compose(middlewareStack);
+
+  const client: HubSpotClient = {
+    send(operation: any): any {
+      if (
+        operation._kind === 'syntheticStreaming' ||
+        operation._kind === 'synthetic'
+      ) {
+        return operation.run({ client });
+      }
+      const ctx: MiddlewareContext = { operation };
+      return run(ctx).then((response) => {
+        assertSuccess(response);
+        return response.bodyJson;
+      });
+    },
+    async sendWithResponse<TOutput>(
+      operation: Operation<TOutput>
+    ): Promise<HubSpotApiResponse<TOutput>> {
+      const ctx: MiddlewareContext = { operation };
+      const response = await run(ctx);
+      assertSuccess(response);
+      return {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        data: response.bodyJson as TOutput,
+      };
+    },
+  };
+
+  return client;
+}

package/src/server/api-client-core/codegen-helpers/file-op-wrappers.ts

@@ -0,0 +1,25 @@
+import type { Operation } from '../types.ts';
+
+export function postProcessFileUploadOp<T>(
+  operation: Operation<T>
+): Operation<T> {
+  if (operation.body && typeof operation.body === 'object') {
+    const body = operation.body as Record<string, unknown>;
+    if (body.options !== undefined) {
+      operation.body = { ...body, options: JSON.stringify(body.options) };
+    }
+  }
+  return operation;
+}
+
+export function postProcessFileReplaceOp<T>(
+  operation: Operation<T>
+): Operation<T> {
+  if (operation.body && typeof operation.body === 'object') {
+    const body = operation.body as Record<string, unknown>;
+    if (body.options !== undefined) {
+      operation.body = { ...body, options: JSON.stringify(body.options) };
+    }
+  }
+  return operation;
+}

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

@@ -0,0 +1,31 @@
+import type { ApiResponse } from './types.ts';
+
+/**
+ * Error thrown when the HubSpot API returns a non-2xx HTTP response.
+ *
+ * Captures the full response metadata so callers can inspect the status code,
+ * headers, and parsed error body for diagnostics or retry logic.
+ */
+export class HubSpotApiError extends Error {
+  /** HTTP status code returned by the API (e.g. `404`, `429`). */
+  public readonly statusCode: number;
+  /** HTTP status text accompanying the status code (e.g. `"Not Found"`). */
+  public readonly statusText: string;
+  /** Response headers as key-value pairs. */
+  public readonly headers: Record<string, string>;
+  /** Parsed JSON body of the error response, if any. */
+  public readonly body: unknown;
+
+  /**
+   * @param response - The raw {@link ApiResponse} from the middleware pipeline
+   *   that triggered the error.
+   */
+  constructor(response: ApiResponse) {
+    super(`HubSpot API error: ${response.status} ${response.statusText}`);
+    this.name = 'HubSpotApiError';
+    this.statusCode = response.status;
+    this.statusText = response.statusText;
+    this.headers = response.headers;
+    this.body = response.bodyJson;
+  }
+}

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

@@ -0,0 +1,49 @@
+/**
+ * HubSpot API client for Node.js.
+ *
+ * Provides a plugin-based, middleware-driven HTTP client for the HubSpot REST
+ * API with full TypeScript types generated from HubSpot's OpenAPI specs.
+ *
+ * @example
+ * ```ts
+ * import { createHubSpotClient, op } from '@hubspot/api-client-core';
+ * import { fetchTransportPlugin } from '@hubspot/api-client-core/plugins';
+ *
+ * const client = createHubSpotClient({
+ *   plugins: [fetchTransportPlugin({ getAccessToken: () => 'my-token' })],
+ * });
+ *
+ * const contact = await client.send(
+ *   op.get('/crm/v3/objects/contacts/{contactId}', {
+ *     pathParams: { contactId: '123' },
+ *   }),
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export type {
+  ApiResponse,
+  CreateHubSpotClientOptions,
+  HubSpotApiResponse,
+  HubSpotClient,
+  Middleware,
+  MiddlewareContext,
+  Next,
+  Operation,
+  PaginatedItem,
+  PaginatedResponse,
+  Plugin,
+  PluginAPI,
+  SyntheticOperation,
+  SyntheticOperationContext,
+  SyntheticStreamingOperation,
+} from './types.ts';
+export { createHubSpotClient } from './client.ts';
+export { HubSpotApiError } from './errors.ts';
+export type { BinaryData } from './binary-data.ts';
+export { createBinaryData, isBinaryData } from './binary-data.ts';
+export { op } from './op.ts';
+export { pagination } from './pagination.ts';
+export * from './apis/index.generated.ts';

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

@@ -0,0 +1,61 @@
+import type { Operation } from './types.ts';
+
+/** Optional fields for constructing an {@link Operation}. */
+type OperationFields = {
+  pathParams?: Record<string, unknown>;
+  queryParams?: Record<string, unknown>;
+  body?: unknown;
+  /** Defaults to `"application/json"` when omitted. */
+  contentType?: string;
+  headers?: Record<string, string>;
+};
+
+/**
+ * Internal helper that assembles an {@link Operation} from its constituent parts.
+ * Sets `contentType` to `"application/json"` when not explicitly provided.
+ */
+const createOp = <T = unknown>(
+  method: Operation['method'],
+  path: string,
+  fields?: OperationFields
+): Operation<T> => {
+  const operation = (fields ?? {}) as Operation<T>;
+  operation.method = method;
+  operation.path = path;
+  operation.contentType ??= 'application/json';
+  return operation;
+};
+
+/**
+ * Factory for building typed {@link Operation} descriptors.
+ *
+ * Each method corresponds to an HTTP verb and returns an `Operation` that can
+ * be passed to {@link HubSpotClient.send}. The `contentType` defaults to
+ * `"application/json"` unless overridden in `fields`.
+ *
+ * @example
+ * ```ts
+ * const getContact = op.get<Contact>('/crm/v3/objects/contacts/{contactId}', {
+ *   pathParams: { contactId: '123' },
+ *   headers: { 'X-Custom': 'value' },
+ * });
+ * const contact = await client.send(getContact);
+ * ```
+ */
+export const op = {
+  /** Creates a `GET` operation. */
+  get: <T = unknown>(path: string, fields?: OperationFields): Operation<T> =>
+    createOp('get', path, fields),
+  /** Creates a `POST` operation. */
+  post: <T = unknown>(path: string, fields?: OperationFields): Operation<T> =>
+    createOp('post', path, fields),
+  /** Creates a `PUT` operation. */
+  put: <T = unknown>(path: string, fields?: OperationFields): Operation<T> =>
+    createOp('put', path, fields),
+  /** Creates a `DELETE` operation. */
+  del: <T = unknown>(path: string, fields?: OperationFields): Operation<T> =>
+    createOp('delete', path, fields),
+  /** Creates a `PATCH` operation. */
+  patch: <T = unknown>(path: string, fields?: OperationFields): Operation<T> =>
+    createOp('patch', path, fields),
+};

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

@@ -0,0 +1,106 @@
+import type {
+  Operation,
+  PaginatedItem,
+  PaginatedResponse,
+  SyntheticOperation,
+  SyntheticStreamingOperation,
+} from './types.ts';
+
+/**
+ * Helpers for automatically traversing HubSpot's cursor-based paginated
+ * endpoints. Each method wraps an {@link Operation} that returns a
+ * {@link PaginatedResponse} and follows the `paging.next.after` cursor
+ * until all pages have been fetched.
+ */
+export const pagination = {
+  /**
+   * Collects every item across all pages into a single array.
+   *
+   * Repeatedly sends the given operation, advancing the `after` cursor
+   * each time, until there are no more pages or the optional `limit` is
+   * reached. Returns a {@link SyntheticOperation} that resolves to the
+   * full array.
+   *
+   * @typeParam TOutput - The paginated response type returned by the API.
+   * @param operation - A paginated API operation to iterate over.
+   * @param options - Optional settings.
+   * @param options.limit - Maximum number of items to collect. Pagination
+   *   stops as soon as this count is reached.
+   * @returns A synthetic operation that resolves to an array of all collected items.
+   *
+   * @example
+   * ```ts
+   * const allContacts = await client.send(
+   *   pagination.getAll(crmContacts.basic.getContacts()),
+   * );
+   * ```
+   */
+  getAll<TOutput extends PaginatedResponse>(
+    operation: Operation<TOutput>,
+    options?: { limit?: number }
+  ): SyntheticOperation<PaginatedItem<TOutput>[]> {
+    return {
+      _kind: 'synthetic',
+      async run(ctx) {
+        const items: PaginatedItem<TOutput>[] = [];
+        const limit = options?.limit;
+        let after: string | undefined;
+        do {
+          const op = {
+            ...operation,
+            queryParams: { ...operation.queryParams, after },
+          };
+          const page = (await ctx.client.send(op)) as TOutput;
+          const results = page.results as PaginatedItem<TOutput>[];
+          if (limit !== undefined && items.length + results.length >= limit) {
+            items.push(...results.slice(0, limit - items.length));
+            break;
+          }
+          items.push(...results);
+          after = page.paging?.next?.after;
+        } while (after);
+        return items;
+      },
+    };
+  },
+
+  /**
+   * Streams items page-by-page via an async generator, yielding each item
+   * as it arrives rather than buffering the entire result set in memory.
+   *
+   * Useful for very large datasets where holding all items in memory is
+   * impractical.
+   *
+   * @typeParam TOutput - The paginated response type returned by the API.
+   * @param operation - A paginated API operation to iterate over.
+   * @returns A synthetic streaming operation that yields items one at a time.
+   *
+   * @example
+   * ```ts
+   * for await (const contact of client.send(
+   *   pagination.getAllStream(crmContacts.basic.getContacts()),
+   * )) {
+   *   console.log(contact.id);
+   * }
+   * ```
+   */
+  getAllStream<TOutput extends PaginatedResponse>(
+    operation: Operation<TOutput>
+  ): SyntheticStreamingOperation<PaginatedItem<TOutput>> {
+    return {
+      _kind: 'syntheticStreaming',
+      async *run(ctx) {
+        let after: string | undefined;
+        do {
+          const op = {
+            ...operation,
+            queryParams: { ...operation.queryParams, after },
+          };
+          const page = (await ctx.client.send(op)) as TOutput;
+          yield* page.results as PaginatedItem<TOutput>[];
+          after = page.paging?.next?.after;
+        } while (after);
+      },
+    };
+  },
+};