@superblocksteam/sdk-api 0.0.4

package/src/integrations/pagerduty/README.md

@@ -0,0 +1,478 @@
+# PagerDuty Client
+
+Create incidents, manage services, and interact with PagerDuty's incident management platform.
+
+## Methods
+
+| Method                                   | Description                                           |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any PagerDuty API request with schema validation |
+
+## Usage
+
+### Create an Incident
+
+```typescript
+import { api, z, pagerduty } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_PAGERDUTY = "a1b2c3d4-5678-90ab-cdef-pagerdu00001";
+
+const IncidentSchema = z.object({
+  id: z.string(),
+  type: z.literal("incident"),
+  self: z.string(),
+  html_url: z.string(),
+  incident_number: z.number(),
+  title: z.string(),
+  description: z.string().nullable(),
+  status: z.string(), // triggered, acknowledged, resolved
+  urgency: z.string(), // high, low
+  created_at: z.string(),
+  service: z.object({
+    id: z.string(),
+    type: z.string(),
+    summary: z.string(),
+  }),
+  assignments: z.array(
+    z.object({
+      at: z.string(),
+      assignee: z.object({
+        id: z.string(),
+        type: z.string(),
+        summary: z.string(),
+      }),
+    }),
+  ),
+});
+
+const CreateIncidentResponseSchema = z.object({
+  incident: IncidentSchema,
+});
+
+export default api({
+  integrations: {
+    pagerduty: pagerduty(PROD_PAGERDUTY),
+  },
+  name: "PagerDutyExample",
+  input: z.object({
+    title: z.string(),
+    serviceId: z.string(),
+    urgency: z.enum(["high", "low"]),
+  }),
+  output: z.object({
+    incidentId: z.string(),
+    incidentNumber: z.number(),
+  }),
+  async run(ctx, { title, serviceId, urgency }) {
+    const result = await ctx.integrations.pagerduty.apiRequest(
+      {
+        method: "POST",
+        path: "/incidents",
+        body: {
+          incident: {
+            type: "incident",
+            title: title,
+            service: {
+              id: serviceId,
+              type: "service_reference",
+            },
+            urgency: urgency,
+            body: {
+              type: "incident_body",
+              details: "Created via API",
+            },
+          },
+        },
+      },
+      { response: CreateIncidentResponseSchema },
+    );
+
+    return {
+      incidentId: result.incident.id,
+      incidentNumber: result.incident.incident_number,
+    };
+  },
+});
+```
+
+### List Incidents
+
+```typescript
+const ListIncidentsResponseSchema = z.object({
+  incidents: z.array(IncidentSchema),
+  limit: z.number(),
+  offset: z.number(),
+  total: z.number().nullable(),
+  more: z.boolean(),
+});
+
+const result = await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "GET",
+    path: "/incidents",
+    params: {
+      "statuses[]": "triggered,acknowledged",
+      urgencies: "high",
+      limit: 25,
+      sort_by: "created_at:desc",
+    },
+  },
+  { response: ListIncidentsResponseSchema },
+);
+
+result.incidents.forEach((incident) => {
+  console.log(
+    `#${incident.incident_number}: ${incident.title} (${incident.status})`,
+  );
+});
+```
+
+### Get an Incident
+
+```typescript
+const result = await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "GET",
+    path: `/incidents/${incidentId}`,
+  },
+  { response: z.object({ incident: IncidentSchema }) },
+);
+```
+
+### Update Incident Status
+
+```typescript
+await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "PUT",
+    path: `/incidents/${incidentId}`,
+    body: {
+      incident: {
+        type: "incident_reference",
+        status: "acknowledged", // or "resolved"
+      },
+    },
+  },
+  { response: z.object({ incident: IncidentSchema }) },
+);
+```
+
+### Add a Note to Incident
+
+```typescript
+const NoteSchema = z.object({
+  id: z.string(),
+  content: z.string(),
+  created_at: z.string(),
+  user: z.object({
+    id: z.string(),
+    summary: z.string(),
+  }),
+});
+
+const result = await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "POST",
+    path: `/incidents/${incidentId}/notes`,
+    body: {
+      note: {
+        content: "Investigating the root cause",
+      },
+    },
+  },
+  { response: z.object({ note: NoteSchema }) },
+);
+```
+
+### List Services
+
+```typescript
+const ServiceSchema = z.object({
+  id: z.string(),
+  type: z.literal("service"),
+  self: z.string(),
+  html_url: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  status: z.string(), // active, warning, critical, maintenance, disabled
+  created_at: z.string(),
+});
+
+const ListServicesResponseSchema = z.object({
+  services: z.array(ServiceSchema),
+  limit: z.number(),
+  offset: z.number(),
+  more: z.boolean(),
+});
+
+const result = await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "GET",
+    path: "/services",
+    params: {
+      limit: 50,
+      sort_by: "name",
+    },
+  },
+  { response: ListServicesResponseSchema },
+);
+```
+
+### Get On-Call Users
+
+```typescript
+const OnCallSchema = z.object({
+  escalation_policy: z.object({
+    id: z.string(),
+    summary: z.string(),
+  }),
+  escalation_level: z.number(),
+  schedule: z
+    .object({
+      id: z.string(),
+      summary: z.string(),
+    })
+    .nullable(),
+  user: z.object({
+    id: z.string(),
+    summary: z.string(),
+    email: z.string(),
+  }),
+  start: z.string(),
+  end: z.string(),
+});
+
+const ListOnCallsResponseSchema = z.object({
+  oncalls: z.array(OnCallSchema),
+});
+
+const result = await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "GET",
+    path: "/oncalls",
+    params: {
+      "escalation_policy_ids[]": policyId,
+      include: "users",
+    },
+  },
+  { response: ListOnCallsResponseSchema },
+);
+
+result.oncalls.forEach((oncall) => {
+  console.log(`${oncall.user.summary} is on-call until ${oncall.end}`);
+});
+```
+
+### Trigger Event via Events API
+
+```typescript
+const EventResponseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  dedup_key: z.string(),
+});
+
+// Note: Events API uses different base URL
+const result = await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "POST",
+    path: "/v2/enqueue",
+    body: {
+      routing_key: "your-integration-key",
+      event_action: "trigger",
+      dedup_key: "unique-incident-key",
+      payload: {
+        summary: "Server CPU above 90%",
+        severity: "critical",
+        source: "monitoring-system",
+        timestamp: new Date().toISOString(),
+        custom_details: {
+          cpu_usage: 95,
+          server: "web-01",
+        },
+      },
+    },
+  },
+  { response: EventResponseSchema },
+);
+```
+
+### Resolve via Events API
+
+```typescript
+await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "POST",
+    path: "/v2/enqueue",
+    body: {
+      routing_key: "your-integration-key",
+      event_action: "resolve",
+      dedup_key: "unique-incident-key", // Same as trigger
+    },
+  },
+  { response: EventResponseSchema },
+);
+```
+
+## 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 pagerduty.createIncident({ ... });
+await pagerduty.listServices();
+
+// CORRECT - Use apiRequest
+await ctx.integrations.pagerduty.apiRequest(
+  { method: "POST", path: "/incidents", body: { incident: { ... } } },
+  { response: CreateIncidentResponseSchema }
+);
+```
+
+### Wrap Objects in Parent Key
+
+PagerDuty wraps objects:
+
+```typescript
+// WRONG
+const body = {
+  title: "Incident title",
+  service: { ... },
+};
+
+// CORRECT
+const body = {
+  incident: {
+    type: "incident",
+    title: "Incident title",
+    service: { ... },
+  },
+};
+```
+
+### Type References
+
+Use `_reference` types for associations:
+
+```typescript
+const body = {
+  incident: {
+    type: "incident",
+    title: "Server down",
+    service: {
+      id: "P123ABC",
+      type: "service_reference", // Not "service"
+    },
+    escalation_policy: {
+      id: "P456DEF",
+      type: "escalation_policy_reference",
+    },
+  },
+};
+```
+
+### Array Parameters
+
+Array parameters need special syntax:
+
+```typescript
+// WRONG
+params: { statuses: ["triggered", "acknowledged"] }
+
+// CORRECT - Use [] suffix
+params: { "statuses[]": "triggered,acknowledged" }
+
+// Or multiple params
+params: { "statuses[]": ["triggered", "acknowledged"] }
+```
+
+### Two APIs: REST and Events
+
+PagerDuty has two different APIs:
+
+```typescript
+// REST API - For managing incidents, services, etc.
+// Base URL: https://api.pagerduty.com
+const path = "/incidents";
+
+// Events API - For triggering/resolving from monitoring
+// Base URL: https://events.pagerduty.com
+const path = "/v2/enqueue";
+```
+
+### From Header Required
+
+Some endpoints require a `From` header with user email:
+
+```typescript
+const result = await ctx.integrations.pagerduty.apiRequest(
+  {
+    method: "POST",
+    path: "/incidents",
+    body: { incident: { ... } },
+    headers: {
+      From: "user@example.com",  // Required for creating incidents
+    },
+  },
+  { response: CreateIncidentResponseSchema }
+);
+```
+
+### Pagination
+
+PagerDuty uses offset-based pagination:
+
+```typescript
+async function getAllIncidents(pagerduty: PagerDutyClient) {
+  const allIncidents: Incident[] = [];
+  let offset = 0;
+  const limit = 100;
+
+  while (true) {
+    const result = await ctx.integrations.pagerduty.apiRequest(
+      {
+        method: "GET",
+        path: "/incidents",
+        params: { limit, offset },
+      },
+      { response: ListIncidentsResponseSchema },
+    );
+
+    allIncidents.push(...result.incidents);
+    if (!result.more) break;
+    offset += limit;
+  }
+
+  return allIncidents;
+}
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.pagerduty.apiRequest(
+    { method: "POST", path: "/incidents", body: { ... } },
+    { response: CreateIncidentResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [PagerDuty REST API](https://developer.pagerduty.com/api-reference/)
+- [Incidents](https://developer.pagerduty.com/api-reference/af59f6f7f6230-list-incidents)
+- [Services](https://developer.pagerduty.com/api-reference/e960cca205c0f-list-services)
+- [Events API v2](https://developer.pagerduty.com/api-reference/b3A6Mjc0ODI1Nw-send-an-event-to-pager-duty)

package/src/integrations/pagerduty/client.ts

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

package/src/integrations/pagerduty/index.ts

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

package/src/integrations/pagerduty/types.ts

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