@superblocksteam/sdk-api 0.0.4

package/src/integrations/asana/README.md

@@ -0,0 +1,423 @@
+# Asana Client
+
+Create tasks, manage projects, and track work in Asana.
+
+## Methods
+
+| Method                                   | Description                                       |
+| ---------------------------------------- | ------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Asana API request with schema validation |
+
+## Usage
+
+### Create a Task
+
+```typescript
+import { api, z, asana } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_ASANA = "a1b2c3d4-5678-90ab-cdef-asana0000001";
+
+const TaskSchema = z.object({
+  gid: z.string(),
+  name: z.string(),
+  notes: z.string(),
+  completed: z.boolean(),
+  due_on: z.string().nullable(),
+  assignee: z.object({ gid: z.string(), name: z.string() }).nullable(),
+  projects: z.array(z.object({ gid: z.string(), name: z.string() })),
+});
+
+const CreateTaskResponseSchema = z.object({
+  data: TaskSchema,
+});
+
+export default api({
+  name: "AsanaExample",
+  integrations: {
+    asana: asana(PROD_ASANA),
+  },
+  input: z.object({
+    projectId: z.string(),
+    name: z.string(),
+    description: z.string(),
+  }),
+  output: z.object({
+    taskId: z.string(),
+  }),
+  async run(ctx, { projectId, name, description }) {
+    const result = await ctx.integrations.asana.apiRequest(
+      {
+        method: "POST",
+        path: "/api/1.0/tasks",
+        body: {
+          data: {
+            name: name,
+            notes: description,
+            projects: [projectId],
+          },
+        },
+      },
+      { response: CreateTaskResponseSchema },
+    );
+
+    return { taskId: result.data.gid };
+  },
+});
+```
+
+### Get Tasks in a Project
+
+```typescript
+const ListTasksResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      gid: z.string(),
+      name: z.string(),
+      completed: z.boolean(),
+    }),
+  ),
+  next_page: z
+    .object({
+      offset: z.string(),
+      uri: z.string(),
+    })
+    .nullable(),
+});
+
+const result = await ctx.integrations.asana.apiRequest(
+  {
+    method: "GET",
+    path: `/api/1.0/projects/${projectId}/tasks`,
+    params: {
+      opt_fields: "name,completed,due_on,assignee.name",
+      completed_since: "now", // Only incomplete tasks
+    },
+  },
+  { response: ListTasksResponseSchema },
+);
+
+result.data.forEach((task) => {
+  console.log(`${task.completed ? "✓" : "○"} ${task.name}`);
+});
+```
+
+### Update a Task
+
+```typescript
+const result = await ctx.integrations.asana.apiRequest(
+  {
+    method: "PUT",
+    path: `/api/1.0/tasks/${taskId}`,
+    body: {
+      data: {
+        completed: true,
+        notes: "Task completed successfully",
+      },
+    },
+  },
+  { response: z.object({ data: TaskSchema }) },
+);
+```
+
+### Assign a Task
+
+```typescript
+const result = await ctx.integrations.asana.apiRequest(
+  {
+    method: "PUT",
+    path: `/api/1.0/tasks/${taskId}`,
+    body: {
+      data: {
+        assignee: userId, // User GID
+        due_on: "2024-12-31",
+      },
+    },
+  },
+  { response: z.object({ data: TaskSchema }) },
+);
+```
+
+### List Projects
+
+```typescript
+const ListProjectsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      gid: z.string(),
+      name: z.string(),
+      archived: z.boolean(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.asana.apiRequest(
+  {
+    method: "GET",
+    path: "/api/1.0/projects",
+    params: {
+      workspace: workspaceId,
+      opt_fields: "name,archived,owner.name",
+      archived: false,
+    },
+  },
+  { response: ListProjectsResponseSchema },
+);
+```
+
+### Create a Project
+
+```typescript
+const CreateProjectResponseSchema = z.object({
+  data: z.object({
+    gid: z.string(),
+    name: z.string(),
+  }),
+});
+
+const result = await ctx.integrations.asana.apiRequest(
+  {
+    method: "POST",
+    path: "/api/1.0/projects",
+    body: {
+      data: {
+        name: "Q1 Marketing Campaign",
+        workspace: workspaceId,
+        team: teamId, // Required for team workspaces
+        default_view: "list",
+        notes: "Project description here",
+      },
+    },
+  },
+  { response: CreateProjectResponseSchema },
+);
+```
+
+### Add a Comment to a Task
+
+```typescript
+const StoryResponseSchema = z.object({
+  data: z.object({
+    gid: z.string(),
+    text: z.string(),
+    created_at: z.string(),
+  }),
+});
+
+const result = await ctx.integrations.asana.apiRequest(
+  {
+    method: "POST",
+    path: `/api/1.0/tasks/${taskId}/stories`,
+    body: {
+      data: {
+        text: "Great progress on this task!",
+      },
+    },
+  },
+  { response: StoryResponseSchema },
+);
+```
+
+### Search Tasks
+
+```typescript
+const SearchResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      gid: z.string(),
+      name: z.string(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.asana.apiRequest(
+  {
+    method: "GET",
+    path: "/api/1.0/workspaces/{workspace_gid}/tasks/search",
+    params: {
+      "text.value": "urgent",
+      completed: false,
+      "assignee.any": userId,
+      sort_by: "due_date",
+      sort_ascending: true,
+    },
+  },
+  { response: SearchResponseSchema },
+);
+```
+
+### Get Subtasks
+
+```typescript
+const result = await ctx.integrations.asana.apiRequest(
+  {
+    method: "GET",
+    path: `/api/1.0/tasks/${taskId}/subtasks`,
+    params: {
+      opt_fields: "name,completed,assignee.name",
+    },
+  },
+  { response: ListTasksResponseSchema },
+);
+```
+
+## 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 asana.createTask({ ... });
+await asana.getTasks({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.asana.apiRequest(
+  { method: "POST", path: "/api/1.0/tasks", body: { data: { ... } } },
+  { response: CreateTaskResponseSchema }
+);
+```
+
+### Data Wrapper
+
+Asana wraps request bodies and responses in a `data` object:
+
+```typescript
+// Request body
+const body = {
+  data: {
+    // Wrapped in data
+    name: "Task name",
+    notes: "Description",
+  },
+};
+
+// Response
+const schema = z.object({
+  data: TaskSchema, // Wrapped in data
+});
+```
+
+### opt_fields Parameter
+
+Use `opt_fields` to specify which fields to return:
+
+```typescript
+// Without opt_fields, you get minimal data
+const params = {};
+
+// With opt_fields, you get specific fields
+const params = {
+  opt_fields: "name,completed,due_on,assignee.name,projects.name",
+};
+
+// Nested fields use dot notation
+// assignee.name returns { assignee: { gid, name } }
+```
+
+### GID vs ID
+
+Asana uses `gid` (Global ID) as the identifier:
+
+```typescript
+// WRONG - Using "id"
+const task = { id: "123456" };
+
+// CORRECT - Using "gid"
+const task = { gid: "123456" };
+```
+
+### Workspace vs Team
+
+- **Workspace**: Container for all projects and tasks
+- **Team**: Required when creating projects in organizations
+
+```typescript
+// Personal workspace - workspace only
+const body = {
+  data: {
+    name: "Project",
+    workspace: workspaceId,
+  },
+};
+
+// Organization - workspace and team required
+const body = {
+  data: {
+    name: "Project",
+    workspace: workspaceId,
+    team: teamId,
+  },
+};
+```
+
+### Date Formats
+
+Asana uses ISO date format (YYYY-MM-DD):
+
+```typescript
+const body = {
+  data: {
+    due_on: "2024-12-31", // Date only
+    due_at: "2024-12-31T17:00:00.000Z", // Date and time
+    start_on: "2024-12-01",
+  },
+};
+```
+
+### Pagination
+
+Large result sets require pagination:
+
+```typescript
+async function getAllTasks(asana: AsanaClient, projectId: string) {
+  const allTasks: Task[] = [];
+  let offset: string | undefined;
+
+  do {
+    const result = await ctx.integrations.asana.apiRequest(
+      {
+        method: "GET",
+        path: `/api/1.0/projects/${projectId}/tasks`,
+        params: {
+          limit: 100,
+          ...(offset && { offset }),
+        },
+      },
+      { response: ListTasksResponseSchema },
+    );
+
+    allTasks.push(...result.data);
+    offset = result.next_page?.offset;
+  } while (offset);
+
+  return allTasks;
+}
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.asana.apiRequest(
+    { method: "POST", path: "/api/1.0/tasks", body: { data: { ... } } },
+    { response: CreateTaskResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Asana API Documentation](https://developers.asana.com/docs)
+- [Tasks](https://developers.asana.com/reference/tasks)
+- [Projects](https://developers.asana.com/reference/projects)
+- [Search](https://developers.asana.com/reference/searchtasksforworkspace)

package/src/integrations/asana/client.ts

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

package/src/integrations/asana/index.ts

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

package/src/integrations/asana/types.ts

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

package/src/integrations/athena/README.md

@@ -0,0 +1,169 @@
+# Athena Client
+
+Execute SQL queries against Amazon Athena with full type safety and runtime validation.
+
+## Methods
+
+| Method                                      | Description                                                |
+| ------------------------------------------- | ---------------------------------------------------------- |
+| `query<T>(sql, schema, params?, metadata?)` | Execute a SELECT query and return validated, typed results |
+| `execute(sql, params?, metadata?)`          | Execute a statement and return affected row count          |
+
+## Usage
+
+### Basic Query with Schema Validation
+
+```typescript
+import { api, z, athena } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_ATHENA = "a1b2c3d4-5678-90ab-cdef-athena000001";
+
+const LogSchema = z.object({
+  timestamp: z.string(),
+  level: z.string(),
+  message: z.string(),
+  request_id: z.string(),
+});
+
+export default api({
+  name: "AthenaExample",
+  integrations: {
+    athena: athena(PROD_ATHENA),
+  },
+  input: z.object({
+    level: z.string(),
+  }),
+  output: z.object({
+    logs: z.array(LogSchema),
+  }),
+  async run(ctx, { level }) {
+    const logs = await ctx.integrations.athena.query(
+      `SELECT timestamp, level, message, request_id
+       FROM logs
+       WHERE level = $1
+       LIMIT 100`,
+      LogSchema,
+      [level],
+    );
+
+    return { logs };
+  },
+});
+```
+
+### Querying S3 Data
+
+```typescript
+const EventSchema = z.object({
+  event_id: z.string(),
+  event_type: z.string(),
+  user_id: z.string(),
+  created_at: z.string(),
+});
+
+const events = await ctx.integrations.athena.query(
+  `SELECT event_id, event_type, user_id, created_at
+   FROM events
+   WHERE date_partition = $1
+     AND event_type = $2`,
+  EventSchema,
+  ["2024-01-15", "purchase"],
+);
+```
+
+### Aggregation Query
+
+```typescript
+const StatsSchema = z.object({
+  date: z.string(),
+  total_events: z.coerce.number(),
+  unique_users: z.coerce.number(),
+});
+
+const stats = await ctx.integrations.athena.query(
+  `SELECT
+    DATE(created_at) as date,
+    COUNT(*) as total_events,
+    COUNT(DISTINCT user_id) as unique_users
+  FROM events
+  WHERE created_at >= DATE_ADD('day', -7, CURRENT_DATE)
+  GROUP BY DATE(created_at)
+  ORDER BY date DESC`,
+  StatsSchema,
+);
+```
+
+## 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
+
+### Query Execution Time
+
+Athena queries can take time to execute. Consider the data size being scanned.
+
+### BIGINT Values Returned as Strings
+
+```typescript
+const schema = z.object({
+  count: z.coerce.number(),
+});
+```
+
+### Schema Parameter is Required
+
+```typescript
+// CORRECT - Schema is required
+const logs = await ctx.integrations.athena.query(
+  "SELECT * FROM logs",
+  LogSchema,
+);
+```
+
+### NULL Handling
+
+```typescript
+const schema = z.object({
+  message: z.string(),
+  metadata: z.string().nullable(),
+});
+```
+
+### Partition Filters
+
+Always use partition filters when possible to reduce data scanned:
+
+```typescript
+// GOOD - Uses partition filter
+const logs = await ctx.integrations.athena.query(
+  "SELECT * FROM logs WHERE date_partition = $1",
+  LogSchema,
+  ["2024-01-15"],
+);
+```
+
+## Error Handling
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const logs = await ctx.integrations.athena.query(
+    "SELECT * FROM logs",
+    LogSchema,
+  );
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    console.error("Row index:", error.details.rowIndex);
+    console.error("Validation errors:", error.details.errors);
+  }
+}
+```
+
+## API Reference
+
+- [Amazon Athena Documentation](https://docs.aws.amazon.com/athena/)
+- [Athena SQL Reference](https://docs.aws.amazon.com/athena/latest/ug/ddl-sql-reference.html)
+- [Athena Data Types](https://docs.aws.amazon.com/athena/latest/ug/data-types.html)