@superblocksteam/sdk-api 0.0.4

package/src/integrations/zendesk/README.md

@@ -0,0 +1,446 @@
+# Zendesk Client
+
+Create tickets, manage users, and interact with Zendesk's customer support platform.
+
+## Methods
+
+| Method                                   | Description                                         |
+| ---------------------------------------- | --------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Zendesk API request with schema validation |
+
+## Usage
+
+### Create a Ticket
+
+```typescript
+import { api, z, zendesk } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_ZENDESK = "a1b2c3d4-5678-90ab-cdef-zendesk00001";
+
+const TicketSchema = z.object({
+  id: z.number(),
+  url: z.string(),
+  subject: z.string(),
+  description: z.string(),
+  status: z.string(), // new, open, pending, hold, solved, closed
+  priority: z.string().nullable(), // low, normal, high, urgent
+  requester_id: z.number(),
+  assignee_id: z.number().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+  tags: z.array(z.string()),
+});
+
+const CreateTicketResponseSchema = z.object({
+  ticket: TicketSchema,
+});
+
+export default api({
+  integrations: {
+    zendesk: zendesk(PROD_ZENDESK),
+  },
+  name: "ZendeskExample",
+  input: z.object({
+    subject: z.string(),
+    description: z.string(),
+    requesterEmail: z.string().email(),
+  }),
+  output: z.object({
+    ticketId: z.number(),
+  }),
+  async run(ctx, { subject, description, requesterEmail }) {
+    const result = await ctx.integrations.zendesk.apiRequest(
+      {
+        method: "POST",
+        path: "/api/v2/tickets.json",
+        body: {
+          ticket: {
+            subject: subject,
+            comment: { body: description },
+            requester: { email: requesterEmail },
+            priority: "normal",
+            tags: ["api-created"],
+          },
+        },
+      },
+      { response: CreateTicketResponseSchema },
+    );
+
+    return { ticketId: result.ticket.id };
+  },
+});
+```
+
+### Get a Ticket
+
+```typescript
+const GetTicketResponseSchema = z.object({
+  ticket: TicketSchema,
+});
+
+const result = await ctx.integrations.zendesk.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/tickets/${ticketId}.json`,
+  },
+  { response: GetTicketResponseSchema },
+);
+
+console.log(`Ticket #${result.ticket.id}: ${result.ticket.subject}`);
+```
+
+### Search Tickets
+
+```typescript
+const SearchResponseSchema = z.object({
+  results: z.array(TicketSchema),
+  count: z.number(),
+  next_page: z.string().nullable(),
+  previous_page: z.string().nullable(),
+});
+
+const result = await ctx.integrations.zendesk.apiRequest(
+  {
+    method: "GET",
+    path: "/api/v2/search.json",
+    params: {
+      query: "type:ticket status:open priority:high",
+      sort_by: "created_at",
+      sort_order: "desc",
+    },
+  },
+  { response: SearchResponseSchema },
+);
+
+result.results.forEach((ticket) => {
+  console.log(`#${ticket.id}: ${ticket.subject} (${ticket.status})`);
+});
+```
+
+### Update a Ticket
+
+```typescript
+await ctx.integrations.zendesk.apiRequest(
+  {
+    method: "PUT",
+    path: `/api/v2/tickets/${ticketId}.json`,
+    body: {
+      ticket: {
+        status: "pending",
+        priority: "high",
+        tags: ["escalated"],
+        comment: {
+          body: "Escalating this ticket to the engineering team.",
+          public: false, // Internal note
+        },
+      },
+    },
+  },
+  { response: GetTicketResponseSchema },
+);
+```
+
+### Add a Comment
+
+```typescript
+await ctx.integrations.zendesk.apiRequest(
+  {
+    method: "PUT",
+    path: `/api/v2/tickets/${ticketId}.json`,
+    body: {
+      ticket: {
+        comment: {
+          body: "Thank you for your patience. We are working on this.",
+          public: true, // Public reply
+        },
+      },
+    },
+  },
+  { response: GetTicketResponseSchema },
+);
+```
+
+### Create a User
+
+```typescript
+const UserSchema = z.object({
+  id: z.number(),
+  url: z.string(),
+  name: z.string(),
+  email: z.string(),
+  role: z.string(), // end-user, agent, admin
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+const CreateUserResponseSchema = z.object({
+  user: UserSchema,
+});
+
+const result = await ctx.integrations.zendesk.apiRequest(
+  {
+    method: "POST",
+    path: "/api/v2/users.json",
+    body: {
+      user: {
+        name: "John Doe",
+        email: "john@example.com",
+        role: "end-user",
+        verified: true,
+      },
+    },
+  },
+  { response: CreateUserResponseSchema },
+);
+```
+
+### List Tickets for a User
+
+```typescript
+const ListTicketsResponseSchema = z.object({
+  tickets: z.array(TicketSchema),
+  next_page: z.string().nullable(),
+  count: z.number(),
+});
+
+const result = await ctx.integrations.zendesk.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/users/${userId}/tickets/requested.json`,
+    params: {
+      sort_by: "created_at",
+      sort_order: "desc",
+    },
+  },
+  { response: ListTicketsResponseSchema },
+);
+```
+
+### Get Ticket Comments
+
+```typescript
+const CommentSchema = z.object({
+  id: z.number(),
+  body: z.string(),
+  author_id: z.number(),
+  public: z.boolean(),
+  created_at: z.string(),
+});
+
+const ListCommentsResponseSchema = z.object({
+  comments: z.array(CommentSchema),
+  next_page: z.string().nullable(),
+});
+
+const result = await ctx.integrations.zendesk.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/tickets/${ticketId}/comments.json`,
+  },
+  { response: ListCommentsResponseSchema },
+);
+
+result.comments.forEach((comment) => {
+  console.log(`${comment.public ? "Public" : "Internal"}: ${comment.body}`);
+});
+```
+
+### Bulk Update Tickets
+
+```typescript
+const BulkUpdateResponseSchema = z.object({
+  job_status: z.object({
+    id: z.string(),
+    url: z.string(),
+    status: z.string(),
+  }),
+});
+
+const result = await ctx.integrations.zendesk.apiRequest(
+  {
+    method: "PUT",
+    path: "/api/v2/tickets/update_many.json",
+    params: {
+      ids: "1,2,3,4,5",
+    },
+    body: {
+      ticket: {
+        status: "solved",
+        tags: ["bulk-closed"],
+      },
+    },
+  },
+  { response: BulkUpdateResponseSchema },
+);
+```
+
+## 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 zendesk.createTicket({ ... });
+await zendesk.searchTickets({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.zendesk.apiRequest(
+  { method: "POST", path: "/api/v2/tickets.json", body: { ticket: { ... } } },
+  { response: CreateTicketResponseSchema }
+);
+```
+
+### Wrap Objects in Parent Key
+
+Zendesk wraps objects in a parent key:
+
+```typescript
+// WRONG - No wrapper
+const body = {
+  subject: "Help!",
+  comment: { body: "I need help" },
+};
+
+// CORRECT - Wrapped in "ticket"
+const body = {
+  ticket: {
+    subject: "Help!",
+    comment: { body: "I need help" },
+  },
+};
+
+// Same for users
+const userBody = {
+  user: {
+    name: "John Doe",
+    email: "john@example.com",
+  },
+};
+```
+
+### .json Suffix in Paths
+
+Zendesk paths end with `.json`:
+
+```typescript
+// WRONG - Missing .json
+const path = "/api/v2/tickets";
+
+// CORRECT - Include .json
+const path = "/api/v2/tickets.json";
+```
+
+### Search Query Syntax
+
+```typescript
+// Type filters
+const query = "type:ticket";
+const query = "type:user";
+
+// Status filters
+const query = "type:ticket status:open";
+const query = "type:ticket status<solved"; // new, open, pending
+
+// Date filters
+const query = "type:ticket created>2024-01-01";
+
+// Priority
+const query = "type:ticket priority:high";
+
+// Assignee
+const query = "type:ticket assignee:none";
+const query = "type:ticket assignee:me";
+
+// Tags
+const query = "type:ticket tags:vip";
+
+// Text search
+const query = 'type:ticket "login issue"';
+
+// Combine multiple
+const query = "type:ticket status:open priority:urgent created>2024-01-01";
+```
+
+### Comments via Update
+
+Comments are added by updating the ticket:
+
+```typescript
+// Can't POST to /tickets/:id/comments directly
+// Instead, PUT to /tickets/:id.json with comment in body
+
+const body = {
+  ticket: {
+    comment: {
+      body: "Your comment here",
+      public: true, // Public reply vs internal note
+    },
+  },
+};
+```
+
+### Pagination
+
+Zendesk uses offset-based pagination:
+
+```typescript
+async function getAllTickets(zendesk: ZendeskClient) {
+  const allTickets: Ticket[] = [];
+  let page = 1;
+
+  while (true) {
+    const result = await ctx.integrations.zendesk.apiRequest(
+      {
+        method: "GET",
+        path: "/api/v2/tickets.json",
+        params: { page, per_page: 100 },
+      },
+      { response: ListTicketsResponseSchema },
+    );
+
+    allTickets.push(...result.tickets);
+    if (!result.next_page) break;
+    page++;
+  }
+
+  return allTickets;
+}
+```
+
+### Rate Limits
+
+Zendesk has rate limits (varies by plan):
+
+```typescript
+// Check X-Rate-Limit and X-Rate-Limit-Remaining headers
+// Default: 400 requests per minute for most endpoints
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.zendesk.apiRequest(
+    { method: "POST", path: "/api/v2/tickets.json", body: { ... } },
+    { response: CreateTicketResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Zendesk API Documentation](https://developer.zendesk.com/api-reference/)
+- [Tickets](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/)
+- [Users](https://developer.zendesk.com/api-reference/ticketing/users/users/)
+- [Search](https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/)

package/src/integrations/zendesk/client.ts

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

package/src/integrations/zendesk/index.ts

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

package/src/integrations/zendesk/types.ts

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