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

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

@@ -0,0 +1,309 @@
+import { describe, expect, it } from 'vitest';
+
+import { createHubSpotClient } from '../client.ts';
+import { HubSpotApiError } from '../errors.ts';
+import type { ApiResponse, Plugin } from '../types.ts';
+
+function stubTransportPlugin(response: ApiResponse): Plugin {
+  return {
+    activate(api) {
+      api.addMiddleware(async () => response);
+    },
+  };
+}
+
+describe('HubSpotApiError', () => {
+  it('is an instance of Error', () => {
+    const error = new HubSpotApiError({
+      status: 404,
+      statusText: 'Not Found',
+      headers: {},
+      bodyJson: null,
+    });
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(HubSpotApiError);
+  });
+
+  it('includes status code and status text in the message', () => {
+    const error = new HubSpotApiError({
+      status: 422,
+      statusText: 'Unprocessable Entity',
+      headers: {},
+      bodyJson: null,
+    });
+    expect(error.message).toBe('HubSpot API error: 422 Unprocessable Entity');
+  });
+
+  it('exposes statusCode, statusText, headers, and body', () => {
+    const headers = { 'retry-after': '30' };
+    const body = { message: 'Rate limit exceeded', category: 'RATE_LIMITS' };
+    const error = new HubSpotApiError({
+      status: 429,
+      statusText: 'Too Many Requests',
+      headers,
+      bodyJson: body,
+    });
+    expect(error.statusCode).toBe(429);
+    expect(error.statusText).toBe('Too Many Requests');
+    expect(error.headers).toBe(headers);
+    expect(error.body).toBe(body);
+  });
+
+  it('has the name "HubSpotApiError"', () => {
+    const error = new HubSpotApiError({
+      status: 500,
+      statusText: 'Internal Server Error',
+      headers: {},
+      bodyJson: null,
+    });
+    expect(error.name).toBe('HubSpotApiError');
+  });
+});
+
+describe('send() error handling', () => {
+  it('throws HubSpotApiError for a 4xx response', async () => {
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 404,
+          statusText: 'Not Found',
+          headers: {},
+          bodyJson: { message: 'Contact not found' },
+        }),
+      ],
+    });
+
+    await expect(
+      client.send({
+        method: 'get',
+        path: '/crm/v3/objects/contacts/123',
+        contentType: 'application/json',
+      })
+    ).rejects.toThrow(HubSpotApiError);
+
+    try {
+      await client.send({
+        method: 'get',
+        path: '/crm/v3/objects/contacts/123',
+        contentType: 'application/json',
+      });
+    } catch (err) {
+      expect(err).toBeInstanceOf(HubSpotApiError);
+      const apiErr = err as HubSpotApiError;
+      expect(apiErr.statusCode).toBe(404);
+      expect(apiErr.body).toEqual({ message: 'Contact not found' });
+    }
+  });
+
+  it('throws HubSpotApiError for a 5xx response', async () => {
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 500,
+          statusText: 'Internal Server Error',
+          headers: {},
+          bodyJson: { message: 'Something went wrong' },
+        }),
+      ],
+    });
+
+    await expect(
+      client.send({
+        method: 'get',
+        path: '/test',
+        contentType: 'application/json',
+      })
+    ).rejects.toThrow(HubSpotApiError);
+  });
+
+  it('throws HubSpotApiError with enhanced message when body is null', async () => {
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 502,
+          statusText: 'Bad Gateway',
+          headers: { 'x-request-id': 'abc' },
+          bodyJson: null,
+        }),
+      ],
+    });
+
+    try {
+      await client.send({
+        method: 'get',
+        path: '/test',
+        contentType: 'application/json',
+      });
+    } catch (err) {
+      expect(err).toBeInstanceOf(HubSpotApiError);
+      const apiErr = err as HubSpotApiError;
+      expect(apiErr.statusCode).toBe(502);
+      expect(apiErr.statusText).toBe('Bad Gateway');
+      expect(apiErr.body).toBeNull();
+      expect(apiErr.message).toBe(
+        'HubSpot API error: 502 Bad Gateway (empty or non-JSON response body)'
+      );
+    }
+  });
+
+  it('returns the typed body for a 2xx response', async () => {
+    const body = { id: '42', properties: { email: 'test@example.com' } };
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 200,
+          statusText: 'OK',
+          headers: {},
+          bodyJson: body,
+        }),
+      ],
+    });
+
+    const result = await client.send({
+      method: 'get',
+      path: '/test',
+      contentType: 'application/json',
+    });
+    expect(result).toEqual(body);
+  });
+
+  it('does not throw for other 2xx status codes', async () => {
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 201,
+          statusText: 'Created',
+          headers: {},
+          bodyJson: { id: '1' },
+        }),
+      ],
+    });
+
+    const result = await client.send({
+      method: 'post',
+      path: '/test',
+      contentType: 'application/json',
+    });
+    expect(result).toEqual({ id: '1' });
+  });
+});
+
+describe('sendWithResponse()', () => {
+  it('returns data, status, statusText, and headers on 2xx', async () => {
+    const body = { id: '42', properties: { email: 'test@example.com' } };
+    const headers = { 'x-request-id': 'abc-123' };
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 200,
+          statusText: 'OK',
+          headers,
+          bodyJson: body,
+        }),
+      ],
+    });
+
+    const result = await client.sendWithResponse({
+      method: 'get',
+      path: '/test',
+      contentType: 'application/json',
+    });
+    expect(result.data).toEqual(body);
+    expect(result.status).toBe(200);
+    expect(result.statusText).toBe('OK');
+    expect(result.headers).toBe(headers);
+  });
+
+  it('returns correct data for 201 Created', async () => {
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 201,
+          statusText: 'Created',
+          headers: {},
+          bodyJson: { id: '1' },
+        }),
+      ],
+    });
+
+    const result = await client.sendWithResponse({
+      method: 'post',
+      path: '/test',
+      contentType: 'application/json',
+    });
+    expect(result.data).toEqual({ id: '1' });
+    expect(result.status).toBe(201);
+    expect(result.statusText).toBe('Created');
+  });
+
+  it('throws HubSpotApiError for a 4xx response', async () => {
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 404,
+          statusText: 'Not Found',
+          headers: {},
+          bodyJson: { message: 'Contact not found' },
+        }),
+      ],
+    });
+
+    await expect(
+      client.sendWithResponse({
+        method: 'get',
+        path: '/crm/v3/objects/contacts/123',
+        contentType: 'application/json',
+      })
+    ).rejects.toThrow(HubSpotApiError);
+  });
+
+  it('throws HubSpotApiError for a 5xx response', async () => {
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 500,
+          statusText: 'Internal Server Error',
+          headers: {},
+          bodyJson: { message: 'Something went wrong' },
+        }),
+      ],
+    });
+
+    await expect(
+      client.sendWithResponse({
+        method: 'get',
+        path: '/test',
+        contentType: 'application/json',
+      })
+    ).rejects.toThrow(HubSpotApiError);
+  });
+
+  it('exposes response headers for rate-limit inspection', async () => {
+    const headers = {
+      'retry-after': '30',
+      'x-hubspot-ratelimit-daily': '250000',
+      'x-hubspot-ratelimit-daily-remaining': '249999',
+    };
+    const client = createHubSpotClient({
+      plugins: [
+        stubTransportPlugin({
+          status: 200,
+          statusText: 'OK',
+          headers,
+          bodyJson: { results: [] },
+        }),
+      ],
+    });
+
+    const result = await client.sendWithResponse({
+      method: 'get',
+      path: '/crm/v3/objects/contacts',
+      contentType: 'application/json',
+    });
+    expect(result.headers['retry-after']).toBe('30');
+    expect(result.headers['x-hubspot-ratelimit-daily']).toBe('250000');
+    expect(result.headers['x-hubspot-ratelimit-daily-remaining']).toBe(
+      '249999'
+    );
+  });
+});

package/src/server/api-client-core/__tests__/operation-headers.test.ts

@@ -0,0 +1,251 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createHubSpotClient } from '../client.ts';
+import { HubSpotApiError } from '../errors.ts';
+import { op } from '../op.ts';
+import { fetchTransportPlugin } from '../plugins/fetch-transport.ts';
+import type { Plugin, PluginAPI } from '../types.ts';
+
+describe('operation headers', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('merges operation headers into the fetch request', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [fetchTransportPlugin({ getAccessToken: () => 'my-token' })],
+    });
+
+    await client.send(
+      op.get('/crm/v3/objects/contacts/{contactId}', {
+        pathParams: { contactId: '1' },
+        headers: { 'X-Custom': 'value' },
+      })
+    );
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const init = fetchMock.mock.calls[0]![1] as RequestInit;
+    expect(init.headers).toMatchObject({
+      Authorization: 'Bearer my-token',
+      'X-Custom': 'value',
+      'Content-Type': 'application/json',
+    });
+  });
+
+  it('transport Authorization overrides operation.headers Authorization', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [
+        fetchTransportPlugin({ getAccessToken: () => 'correct-token' }),
+      ],
+    });
+
+    await client.send(
+      op.get('/test', {
+        headers: { Authorization: 'Bearer attacker' },
+      })
+    );
+
+    const init = fetchMock.mock.calls[0]![1] as RequestInit;
+    const headers = init.headers as Record<string, string>;
+    expect(headers.Authorization).toBe('Bearer correct-token');
+  });
+
+  it('serializes application/x-www-form-urlencoded body and Content-Type', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [fetchTransportPlugin({ getAccessToken: () => 't' })],
+    });
+
+    const body = {
+      grant_type: 'refresh_token',
+      scopes: ['crm.objects.contacts.read', 'crm.objects.deals.read'],
+    };
+    await client.send(
+      op.post('/oauth/v3/token', {
+        body,
+        contentType: 'application/x-www-form-urlencoded',
+      })
+    );
+
+    const init = fetchMock.mock.calls[0]![1] as RequestInit;
+    const headers = init.headers as Record<string, string>;
+    expect(headers['Content-Type']).toBe('application/x-www-form-urlencoded');
+    const expected = new URLSearchParams();
+    expected.append('grant_type', 'refresh_token');
+    expected.append('scopes', 'crm.objects.contacts.read');
+    expected.append('scopes', 'crm.objects.deals.read');
+    expect(init.body).toBe(expected.toString());
+  });
+
+  it('default JSON Content-Type overrides operation Content-Type', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [fetchTransportPlugin({ getAccessToken: () => 't' })],
+    });
+
+    await client.send(
+      op.get('/x', {
+        headers: { 'Content-Type': 'text/plain' },
+      })
+    );
+
+    const init = fetchMock.mock.calls[0]![1] as RequestInit;
+    expect((init.headers as Record<string, string>)['Content-Type']).toBe(
+      'application/json'
+    );
+  });
+
+  it('middleware can read ctx.operation.headers', async () => {
+    let captured: Record<string, string> | undefined;
+    const observePlugin: Plugin = {
+      activate(api: PluginAPI) {
+        api.addMiddleware(async (ctx, next) => {
+          captured = ctx.operation.headers;
+          return next();
+        });
+      },
+    };
+
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [
+        observePlugin,
+        fetchTransportPlugin({ getAccessToken: () => 't' }),
+      ],
+    });
+
+    await client.send(op.get('/x', { headers: { 'X-Trace': 'abc' } }));
+
+    expect(captured).toEqual({ 'X-Trace': 'abc' });
+  });
+});
+
+describe('fetch transport response body parsing', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  const transportOptions = { getAccessToken: () => 'token' };
+
+  it('throws HubSpotApiError for 502 with HTML body', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response('<html><body>Bad Gateway</body></html>', {
+        status: 502,
+        statusText: 'Bad Gateway',
+        headers: { 'Content-Type': 'text/html' },
+      })
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [fetchTransportPlugin(transportOptions)],
+    });
+
+    try {
+      await client.send(op.get('/test'));
+      expect.fail('expected send to throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(HubSpotApiError);
+      const apiErr = err as HubSpotApiError;
+      expect(apiErr.statusCode).toBe(502);
+      expect(apiErr.statusText).toBe('Bad Gateway');
+      expect(apiErr.body).toBeNull();
+      expect(apiErr.message).toContain('502 Bad Gateway');
+      expect(apiErr.message).toContain('(empty or non-JSON response body)');
+    }
+  });
+
+  it('throws HubSpotApiError with parsed body for 404 with valid JSON', async () => {
+    const errorBody = { message: 'Contact not found' };
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify(errorBody), {
+        status: 404,
+        statusText: 'Not Found',
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [fetchTransportPlugin(transportOptions)],
+    });
+
+    try {
+      await client.send(op.get('/test'));
+    } catch (err) {
+      const apiErr = err as HubSpotApiError;
+      expect(apiErr.statusCode).toBe(404);
+      expect(apiErr.body).toEqual(errorBody);
+      expect(apiErr.message).not.toContain('(empty or non-JSON response body)');
+    }
+  });
+
+  it('returns undefined body for 204 No Content', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(
+        new Response(null, { status: 204, statusText: 'No Content' })
+      );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [fetchTransportPlugin(transportOptions)],
+    });
+
+    const result = await client.send(op.del('/test'));
+    expect(result).toBeUndefined();
+  });
+
+  it('rejects with SyntaxError for 200 with invalid JSON', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response('not json', {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = createHubSpotClient({
+      plugins: [fetchTransportPlugin(transportOptions)],
+    });
+
+    await expect(client.send(op.get('/test'))).rejects.toThrow(SyntaxError);
+  });
+});