@superblocksteam/sdk-api 0.0.4

package/src/integrations/gsheets/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Google Sheets integration client.
+ *
+ * @module
+ */
+
+export type {
+  GoogleSheetsClient,
+  GoogleSheetsAction,
+  GoogleSheetsParams,
+} from "./types.js";
+export { GoogleSheetsClientImpl } from "./client.js";

package/src/integrations/gsheets/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Google Sheets client types.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Google Sheets action types.
+ */
+export type GoogleSheetsAction =
+  | "READ_SPREADSHEET"
+  | "READ_SPREADSHEET_RANGE"
+  | "APPEND_SPREADSHEET"
+  | "CREATE_SPREADSHEET_ROWS"
+  | "CLEAR_SPREADSHEET"
+  | "CREATE_WORKSHEET";
+
+/**
+ * Parameters for Google Sheets operations.
+ */
+export interface GoogleSheetsParams {
+  /** Spreadsheet ID */
+  spreadsheetId: string;
+  /** Sheet title/name */
+  sheetTitle?: string;
+  /** Range in A1 notation (e.g., "A1:D10") */
+  range?: string;
+  /** Row number for single row operations */
+  rowNumber?: string;
+  /** Whether to extract first row as header */
+  extractFirstRowHeader?: boolean;
+  /** Header row number */
+  headerRowNumber?: string;
+  /** Data format */
+  format?: string;
+  /** Data to write (JSON string) */
+  data?: string;
+  /** Whether to preserve header row when clearing */
+  preserveHeaderRow?: boolean;
+  /** Whether to include header row in output */
+  includeHeaderRow?: boolean;
+  /** Destination type for writes */
+  writeToDestinationType?: string;
+  /** Body content */
+  body?: string;
+  /** New sheet configuration for CREATE_WORKSHEET action */
+  addSheet?: {
+    sheetTitle: string;
+    rowCount?: string;
+    columnCount?: string;
+  };
+}
+
+/**
+ * Google Sheets client for spreadsheet operations.
+ *
+ * Provides a generic run() method for executing Google Sheets operations.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { sheets: gsheets(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.sheets
+ *
+ * // Read a range
+ * const RowSchema = z.array(z.object({
+ *   name: z.string(),
+ *   email: z.string(),
+ * }));
+ *
+ * const data = await ctx.integrations.sheets.run('READ_SPREADSHEET_RANGE', RowSchema, {
+ *   spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
+ *   sheetTitle: 'Sheet1',
+ *   range: 'A1:B10',
+ *   extractFirstRowHeader: true,
+ * });
+ *
+ * // Append rows
+ * await ctx.integrations.sheets.run('APPEND_SPREADSHEET', z.any(), {
+ *   spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
+ *   sheetTitle: 'Sheet1',
+ *   data: JSON.stringify([{ name: 'John', email: 'john@example.com' }]),
+ * });
+ * ```
+ */
+export interface GoogleSheetsClient extends BaseIntegrationClient {
+  /**
+   * Execute a Google Sheets operation.
+   *
+   * @param action - The operation to perform
+   * @param schema - Zod schema for validating the result
+   * @param params - Operation parameters
+   * @returns The validated result
+   */
+  run<T>(
+    action: GoogleSheetsAction,
+    schema: z.ZodSchema<T>,
+    params: GoogleSheetsParams,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+}

package/src/integrations/hubspot/README.md

@@ -0,0 +1,451 @@
+# HubSpot Client
+
+Manage contacts, deals, companies, and interact with HubSpot's CRM platform.
+
+## Methods
+
+| Method                                   | Description                                         |
+| ---------------------------------------- | --------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any HubSpot API request with schema validation |
+
+## Usage
+
+### Create a Contact
+
+```typescript
+import { api, z, hubspot } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_HUBSPOT = "a1b2c3d4-5678-90ab-cdef-hubspot00001";
+
+const ContactSchema = z.object({
+  id: z.string(),
+  properties: z
+    .object({
+      email: z.string().optional(),
+      firstname: z.string().optional(),
+      lastname: z.string().optional(),
+      phone: z.string().optional(),
+      company: z.string().optional(),
+    })
+    .passthrough(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export default api({
+  integrations: {
+    hubspot: hubspot(PROD_HUBSPOT),
+  },
+  name: "HubSpotExample",
+  input: z.object({
+    email: z.string().email(),
+    firstName: z.string(),
+    lastName: z.string(),
+  }),
+  output: z.object({
+    contactId: z.string(),
+  }),
+  async run(ctx, { email, firstName, lastName }) {
+    const result = await ctx.integrations.hubspot.apiRequest(
+      {
+        method: "POST",
+        path: "/crm/v3/objects/contacts",
+        body: {
+          properties: {
+            email: email,
+            firstname: firstName,
+            lastname: lastName,
+          },
+        },
+      },
+      { response: ContactSchema },
+    );
+
+    return { contactId: result.id };
+  },
+});
+```
+
+### Get a Contact
+
+```typescript
+const contact = await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "GET",
+    path: `/crm/v3/objects/contacts/${contactId}`,
+    params: {
+      properties: "email,firstname,lastname,phone,company,lifecyclestage",
+    },
+  },
+  { response: ContactSchema },
+);
+```
+
+### Search Contacts
+
+```typescript
+const SearchResponseSchema = z.object({
+  total: z.number(),
+  results: z.array(ContactSchema),
+  paging: z
+    .object({
+      next: z
+        .object({
+          after: z.string(),
+        })
+        .optional(),
+    })
+    .optional(),
+});
+
+const result = await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "POST",
+    path: "/crm/v3/objects/contacts/search",
+    body: {
+      filterGroups: [
+        {
+          filters: [
+            {
+              propertyName: "email",
+              operator: "CONTAINS_TOKEN",
+              value: "@example.com",
+            },
+          ],
+        },
+      ],
+      sorts: [{ propertyName: "createdate", direction: "DESCENDING" }],
+      properties: ["email", "firstname", "lastname"],
+      limit: 25,
+    },
+  },
+  { response: SearchResponseSchema },
+);
+```
+
+### Create a Deal
+
+```typescript
+const DealSchema = z.object({
+  id: z.string(),
+  properties: z
+    .object({
+      dealname: z.string().optional(),
+      amount: z.string().optional(),
+      dealstage: z.string().optional(),
+      closedate: z.string().optional(),
+      pipeline: z.string().optional(),
+    })
+    .passthrough(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+const deal = await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "POST",
+    path: "/crm/v3/objects/deals",
+    body: {
+      properties: {
+        dealname: "Enterprise Contract",
+        amount: "50000",
+        dealstage: "qualifiedtobuy",
+        closedate: "2024-12-31",
+        pipeline: "default",
+      },
+    },
+  },
+  { response: DealSchema },
+);
+```
+
+### List Deals
+
+```typescript
+const ListDealsResponseSchema = z.object({
+  results: z.array(DealSchema),
+  paging: z
+    .object({
+      next: z.object({ after: z.string() }).optional(),
+    })
+    .optional(),
+});
+
+const deals = await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "GET",
+    path: "/crm/v3/objects/deals",
+    params: {
+      limit: 50,
+      properties: "dealname,amount,dealstage,closedate",
+    },
+  },
+  { response: ListDealsResponseSchema },
+);
+```
+
+### Create a Company
+
+```typescript
+const CompanySchema = z.object({
+  id: z.string(),
+  properties: z
+    .object({
+      name: z.string().optional(),
+      domain: z.string().optional(),
+      industry: z.string().optional(),
+      phone: z.string().optional(),
+    })
+    .passthrough(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+const company = await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "POST",
+    path: "/crm/v3/objects/companies",
+    body: {
+      properties: {
+        name: "Acme Corp",
+        domain: "acme.com",
+        industry: "Technology",
+        phone: "+1-555-123-4567",
+      },
+    },
+  },
+  { response: CompanySchema },
+);
+```
+
+### Associate Objects
+
+```typescript
+// Associate a contact with a company
+await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "PUT",
+    path: `/crm/v3/objects/contacts/${contactId}/associations/companies/${companyId}/contact_to_company`,
+  },
+  { response: z.object({}).optional() },
+);
+
+// Associate a deal with a contact
+await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "PUT",
+    path: `/crm/v3/objects/deals/${dealId}/associations/contacts/${contactId}/deal_to_contact`,
+  },
+  { response: z.object({}).optional() },
+);
+```
+
+### Update Contact Properties
+
+```typescript
+const updatedContact = await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "PATCH",
+    path: `/crm/v3/objects/contacts/${contactId}`,
+    body: {
+      properties: {
+        phone: "+1-555-987-6543",
+        lifecyclestage: "customer",
+        hs_lead_status: "QUALIFIED",
+      },
+    },
+  },
+  { response: ContactSchema },
+);
+```
+
+### Get Contact Engagements
+
+```typescript
+const EngagementsResponseSchema = z.object({
+  results: z.array(
+    z.object({
+      id: z.string(),
+      properties: z.record(z.unknown()),
+    }),
+  ),
+});
+
+const engagements = await ctx.integrations.hubspot.apiRequest(
+  {
+    method: "GET",
+    path: `/crm/v3/objects/contacts/${contactId}/associations/notes`,
+  },
+  { response: EngagementsResponseSchema },
+);
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await hubspot.createContact({ ... });
+await hubspot.getDeals();
+
+// CORRECT - Use apiRequest
+await ctx.integrations.hubspot.apiRequest(
+  { method: "POST", path: "/crm/v3/objects/contacts", body: { ... } },
+  { response: ContactSchema }
+);
+```
+
+### Property Names are Lowercase
+
+HubSpot properties use lowercase with underscores:
+
+```typescript
+// WRONG - CamelCase
+const body = {
+  properties: {
+    firstName: "John",
+    lastName: "Doe",
+  },
+};
+
+// CORRECT - lowercase
+const body = {
+  properties: {
+    firstname: "John",
+    lastname: "Doe",
+  },
+};
+```
+
+### Amounts as Strings
+
+Deal amounts are strings, not numbers:
+
+```typescript
+// WRONG
+const body = { properties: { amount: 50000 } };
+
+// CORRECT
+const body = { properties: { amount: "50000" } };
+```
+
+### Search Filter Operators
+
+```typescript
+// Available operators
+const operators = [
+  "EQ", // Equals
+  "NEQ", // Not equals
+  "LT", // Less than
+  "LTE", // Less than or equal
+  "GT", // Greater than
+  "GTE", // Greater than or equal
+  "CONTAINS_TOKEN", // Contains (for text)
+  "NOT_CONTAINS_TOKEN",
+  "HAS_PROPERTY", // Property exists
+  "NOT_HAS_PROPERTY",
+];
+
+// Example search
+const body = {
+  filterGroups: [
+    {
+      filters: [
+        { propertyName: "amount", operator: "GTE", value: "10000" },
+        { propertyName: "dealstage", operator: "EQ", value: "closedwon" },
+      ],
+    },
+  ],
+};
+```
+
+### Association Types
+
+Association types follow a naming pattern:
+
+```typescript
+// Contact to Company
+const type = "contact_to_company";
+
+// Deal to Contact
+const type = "deal_to_contact";
+
+// Company to Deal
+const type = "company_to_deal";
+```
+
+### Pagination
+
+HubSpot uses cursor-based pagination:
+
+```typescript
+async function getAllContacts(hubspot: HubSpotClient) {
+  const allContacts: Contact[] = [];
+  let after: string | undefined;
+
+  while (true) {
+    const result = await ctx.integrations.hubspot.apiRequest(
+      {
+        method: "GET",
+        path: "/crm/v3/objects/contacts",
+        params: {
+          limit: 100,
+          ...(after && { after }),
+        },
+      },
+      { response: ListContactsResponseSchema },
+    );
+
+    allContacts.push(...result.results);
+    if (!result.paging?.next?.after) break;
+    after = result.paging.next.after;
+  }
+
+  return allContacts;
+}
+```
+
+### Date Format
+
+Dates use ISO 8601 or Unix timestamp (milliseconds):
+
+```typescript
+const body = {
+  properties: {
+    closedate: "2024-12-31", // ISO date
+    // Or Unix timestamp in milliseconds
+    closedate: "1735689600000",
+  },
+};
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.hubspot.apiRequest(
+    { method: "POST", path: "/crm/v3/objects/contacts", body: { ... } },
+    { response: ContactSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [HubSpot API Documentation](https://developers.hubspot.com/docs/api/overview)
+- [Contacts](https://developers.hubspot.com/docs/api/crm/contacts)
+- [Deals](https://developers.hubspot.com/docs/api/crm/deals)
+- [Companies](https://developers.hubspot.com/docs/api/crm/companies)
+- [Search](https://developers.hubspot.com/docs/api/crm/search)

package/src/integrations/hubspot/client.ts

@@ -0,0 +1,23 @@
+/**
+ * HubSpot client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * HubSpot integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { HubSpotClient } from "./types.js";
+
+/**
+ * Internal implementation of HubSpotClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * HubSpot API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class HubSpotClientImpl
+  extends RestApiIntegrationClient
+  implements HubSpotClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/hubspot/index.ts

@@ -0,0 +1,2 @@
+export { HubSpotClientImpl } from "./client.js";
+export type { HubSpotClient } from "./types.js";

package/src/integrations/hubspot/types.ts

@@ -0,0 +1,36 @@
+/**
+ * HubSpot client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
+
+/**
+ * HubSpot client for API interactions.
+ *
+ * Provides generic API request method for interacting with HubSpot's API.
+ * Use apiRequest() to make calls to any HubSpot API endpoint.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { hubspot: hubspot(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.hubspot
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await hubspot.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/crm/v3/objects/contacts',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface HubSpotClient
+  extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}