@superblocksteam/sdk-api 0.0.4

package/src/integrations/confluence/README.md

@@ -0,0 +1,473 @@
+# Confluence Client
+
+Create pages, manage content, and search in Confluence spaces.
+
+## Methods
+
+| Method                                   | Description                                            |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `apiRequest(options, schema, metadata?)` | Make any Confluence API request with schema validation |
+
+## Usage
+
+### Create a Page
+
+```typescript
+import { api, z, confluence } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_CONFLUENCE = "a1b2c3d4-5678-90ab-cdef-confluen0001";
+
+const PageSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  status: z.string(),
+  title: z.string(),
+  _links: z.object({
+    webui: z.string(),
+    self: z.string(),
+  }),
+});
+
+export default api({
+  name: "ConfluenceExample",
+  integrations: {
+    confluence: confluence(PROD_CONFLUENCE),
+  },
+  input: z.object({
+    spaceKey: z.string(),
+    title: z.string(),
+    content: z.string(),
+  }),
+  output: z.object({
+    pageId: z.string(),
+    url: z.string(),
+  }),
+  async run(ctx, { spaceKey, title, content }) {
+    const result = await ctx.integrations.confluence.apiRequest(
+      {
+        method: "POST",
+        path: "/wiki/api/v2/pages",
+        body: {
+          spaceId: spaceKey, // Space ID
+          status: "current",
+          title: title,
+          body: {
+            representation: "storage",
+            value: `<p>${content}</p>`,
+          },
+        },
+      },
+      { response: PageSchema },
+    );
+
+    return { pageId: result.id, url: result._links.webui };
+  },
+});
+```
+
+### Get a Page
+
+```typescript
+const PageDetailSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.string(),
+  body: z
+    .object({
+      storage: z
+        .object({
+          value: z.string(),
+          representation: z.string(),
+        })
+        .optional(),
+    })
+    .optional(),
+  version: z.object({
+    number: z.number(),
+    createdAt: z.string(),
+  }),
+});
+
+const result = await ctx.integrations.confluence.apiRequest(
+  {
+    method: "GET",
+    path: `/wiki/api/v2/pages/${pageId}`,
+    params: {
+      "body-format": "storage",
+    },
+  },
+  { response: PageDetailSchema },
+);
+
+console.log(`Page: ${result.title} (v${result.version.number})`);
+```
+
+### Update a Page
+
+```typescript
+// First, get current version
+const page = await ctx.integrations.confluence.apiRequest(
+  { method: "GET", path: `/wiki/api/v2/pages/${pageId}` },
+  { response: PageDetailSchema },
+);
+
+// Then update with incremented version
+await ctx.integrations.confluence.apiRequest(
+  {
+    method: "PUT",
+    path: `/wiki/api/v2/pages/${pageId}`,
+    body: {
+      id: pageId,
+      status: "current",
+      title: "Updated Title",
+      body: {
+        representation: "storage",
+        value: "<p>Updated content</p>",
+      },
+      version: {
+        number: page.version.number + 1, // Increment version
+        message: "Updated via API",
+      },
+    },
+  },
+  { response: PageSchema },
+);
+```
+
+### Search Content
+
+```typescript
+const SearchResponseSchema = z.object({
+  results: z.array(
+    z.object({
+      content: z.object({
+        id: z.string(),
+        type: z.string(),
+        title: z.string(),
+      }),
+      excerpt: z.string().optional(),
+    }),
+  ),
+  totalSize: z.number(),
+  _links: z.object({
+    next: z.string().optional(),
+  }),
+});
+
+const result = await ctx.integrations.confluence.apiRequest(
+  {
+    method: "GET",
+    path: "/wiki/rest/api/search",
+    params: {
+      cql: 'type=page AND space="PROJ" AND text~"search term"',
+      limit: 25,
+    },
+  },
+  { response: SearchResponseSchema },
+);
+
+result.results.forEach((r) => {
+  console.log(`${r.content.title}: ${r.excerpt}`);
+});
+```
+
+### List Pages in a Space
+
+```typescript
+const ListPagesResponseSchema = z.object({
+  results: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      status: z.string(),
+    }),
+  ),
+  _links: z.object({
+    next: z.string().optional(),
+  }),
+});
+
+const result = await ctx.integrations.confluence.apiRequest(
+  {
+    method: "GET",
+    path: `/wiki/api/v2/spaces/${spaceId}/pages`,
+    params: {
+      limit: 50,
+      status: "current",
+    },
+  },
+  { response: ListPagesResponseSchema },
+);
+```
+
+### Create a Child Page
+
+```typescript
+const result = await ctx.integrations.confluence.apiRequest(
+  {
+    method: "POST",
+    path: "/wiki/api/v2/pages",
+    body: {
+      spaceId: spaceId,
+      parentId: parentPageId, // Parent page ID
+      status: "current",
+      title: "Child Page Title",
+      body: {
+        representation: "storage",
+        value: "<p>Child page content</p>",
+      },
+    },
+  },
+  { response: PageSchema },
+);
+```
+
+### Add a Comment
+
+```typescript
+const CommentSchema = z.object({
+  id: z.string(),
+  body: z.object({
+    storage: z.object({
+      value: z.string(),
+    }),
+  }),
+});
+
+const result = await ctx.integrations.confluence.apiRequest(
+  {
+    method: "POST",
+    path: `/wiki/api/v2/pages/${pageId}/footer-comments`,
+    body: {
+      body: {
+        representation: "storage",
+        value: "<p>This is a comment</p>",
+      },
+    },
+  },
+  { response: CommentSchema },
+);
+```
+
+### Get Space
+
+```typescript
+const SpaceSchema = z.object({
+  id: z.string(),
+  key: z.string(),
+  name: z.string(),
+  type: z.string(),
+  status: z.string(),
+});
+
+const result = await ctx.integrations.confluence.apiRequest(
+  {
+    method: "GET",
+    path: `/wiki/api/v2/spaces/${spaceId}`,
+  },
+  { response: SpaceSchema },
+);
+```
+
+### Add Labels to a Page
+
+```typescript
+const LabelSchema = z.object({
+  results: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.confluence.apiRequest(
+  {
+    method: "POST",
+    path: `/wiki/rest/api/content/${pageId}/label`,
+    body: [{ name: "documentation" }, { name: "api" }],
+  },
+  { response: LabelSchema },
+);
+```
+
+## 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 confluence.createPage({ ... });
+await confluence.search({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.confluence.apiRequest(
+  { method: "POST", path: "/wiki/api/v2/pages", body: { ... } },
+  { response: PageSchema }
+);
+```
+
+### API Version (v2 vs REST)
+
+Confluence has two API versions:
+
+```typescript
+// V2 API (newer, recommended)
+const v2Path = "/wiki/api/v2/pages";
+
+// REST API (older, some features only here)
+const restPath = "/wiki/rest/api/content";
+
+// Search is only in REST API
+const searchPath = "/wiki/rest/api/search";
+```
+
+### Storage Format for Content
+
+Page content uses Confluence storage format (XHTML-like):
+
+```typescript
+const body = {
+  representation: "storage",
+  value: `
+    <h1>Heading</h1>
+    <p>Paragraph with <strong>bold</strong> and <em>italic</em></p>
+    <ul>
+      <li>List item 1</li>
+      <li>List item 2</li>
+    </ul>
+    <ac:structured-macro ac:name="code">
+      <ac:parameter ac:name="language">javascript</ac:parameter>
+      <ac:plain-text-body><![CDATA[console.log('Hello');]]></ac:plain-text-body>
+    </ac:structured-macro>
+  `,
+};
+```
+
+### Version Number Required for Updates
+
+Updates require incrementing the version number:
+
+```typescript
+// WRONG - Missing version
+const body = {
+  title: "New Title",
+  body: { ... },
+};
+
+// CORRECT - Include incremented version
+const body = {
+  version: {
+    number: currentVersion + 1, // Must increment
+    message: "Update message",
+  },
+  title: "New Title",
+  body: { ... },
+};
+```
+
+### Space ID vs Space Key
+
+V2 API uses space IDs, REST API uses space keys:
+
+```typescript
+// V2 API - uses spaceId
+const v2Body = {
+  spaceId: "123456", // Numeric ID
+};
+
+// REST API - uses spaceKey
+const restBody = {
+  space: { key: "PROJ" }, // Key string
+};
+```
+
+### CQL Syntax (Confluence Query Language)
+
+```typescript
+// Basic search
+const cql = 'type=page AND text~"search term"';
+
+// Space filter
+const cql = 'type=page AND space="PROJ"';
+
+// Created/modified date
+const cql = 'created >= now("-7d")'; // Last 7 days
+const cql = 'lastModified >= "2024-01-01"';
+
+// Label filter
+const cql = 'label = "documentation"';
+
+// Creator filter
+const cql = "creator = currentUser()";
+
+// Ancestor (pages under a specific parent)
+const cql = "ancestor = 123456";
+
+// Combine conditions
+const cql =
+  'type=page AND space="PROJ" AND label="api" ORDER BY lastModified DESC';
+```
+
+### Pagination
+
+Large result sets require pagination:
+
+```typescript
+async function getAllPages(confluence: ConfluenceClient, spaceId: string) {
+  const allPages: Page[] = [];
+  let cursor: string | undefined;
+
+  while (true) {
+    const result = await ctx.integrations.confluence.apiRequest(
+      {
+        method: "GET",
+        path: `/wiki/api/v2/spaces/${spaceId}/pages`,
+        params: {
+          limit: 100,
+          ...(cursor && { cursor }),
+        },
+      },
+      { response: ListPagesResponseSchema },
+    );
+
+    allPages.push(...result.results);
+
+    if (!result._links.next) break;
+    // Extract cursor from next link
+    cursor =
+      new URL(result._links.next).searchParams.get("cursor") ?? undefined;
+  }
+
+  return allPages;
+}
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.confluence.apiRequest(
+    { method: "POST", path: "/wiki/api/v2/pages", body: { ... } },
+    { response: PageSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Confluence Cloud REST API (V2)](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/)
+- [Confluence Cloud REST API (V1)](https://developer.atlassian.com/cloud/confluence/rest/v1/intro/)
+- [CQL Reference](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/)
+- [Storage Format](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html)

package/src/integrations/confluence/client.ts

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

package/src/integrations/confluence/index.ts

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

package/src/integrations/confluence/types.ts

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