@superblocksteam/sdk-api 2.0.105-next.0 → 2.0.105-next.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/README.md +202 -86
  2. package/dist/api/definition.d.ts +11 -6
  3. package/dist/api/definition.d.ts.map +1 -1
  4. package/dist/api/definition.js +19 -12
  5. package/dist/api/definition.js.map +1 -1
  6. package/dist/api/definition.test.js +39 -15
  7. package/dist/api/definition.test.js.map +1 -1
  8. package/dist/errors.d.ts +1 -1
  9. package/dist/errors.js +1 -1
  10. package/dist/index.d.ts +10 -10
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +9 -5
  13. package/dist/index.js.map +1 -1
  14. package/dist/integrations/base/index.d.ts +2 -1
  15. package/dist/integrations/base/index.d.ts.map +1 -1
  16. package/dist/integrations/base/index.js +1 -0
  17. package/dist/integrations/base/index.js.map +1 -1
  18. package/dist/integrations/base/rest-api-client-base.d.ts +48 -0
  19. package/dist/integrations/base/rest-api-client-base.d.ts.map +1 -0
  20. package/dist/integrations/base/rest-api-client-base.js +98 -0
  21. package/dist/integrations/base/rest-api-client-base.js.map +1 -0
  22. package/dist/integrations/base/rest-api-integration-client.d.ts +10 -20
  23. package/dist/integrations/base/rest-api-integration-client.d.ts.map +1 -1
  24. package/dist/integrations/base/rest-api-integration-client.js +10 -65
  25. package/dist/integrations/base/rest-api-integration-client.js.map +1 -1
  26. package/dist/integrations/box/types.d.ts +1 -1
  27. package/dist/integrations/declarations.d.ts +5 -63
  28. package/dist/integrations/declarations.d.ts.map +1 -1
  29. package/dist/integrations/declarations.js +5 -59
  30. package/dist/integrations/declarations.js.map +1 -1
  31. package/dist/integrations/documentation.test.js +0 -2
  32. package/dist/integrations/documentation.test.js.map +1 -1
  33. package/dist/integrations/googledrive/types.d.ts +1 -1
  34. package/dist/integrations/index.d.ts +1 -9
  35. package/dist/integrations/index.d.ts.map +1 -1
  36. package/dist/integrations/index.js +1 -6
  37. package/dist/integrations/index.js.map +1 -1
  38. package/dist/integrations/registry.d.ts +1 -10
  39. package/dist/integrations/registry.d.ts.map +1 -1
  40. package/dist/integrations/registry.js +0 -25
  41. package/dist/integrations/registry.js.map +1 -1
  42. package/dist/integrations/slack/client.d.ts +13 -9
  43. package/dist/integrations/slack/client.d.ts.map +1 -1
  44. package/dist/integrations/slack/client.js +60 -8
  45. package/dist/integrations/slack/client.js.map +1 -1
  46. package/dist/integrations/slack/client.test.d.ts +11 -0
  47. package/dist/integrations/slack/client.test.d.ts.map +1 -0
  48. package/dist/integrations/slack/client.test.js +368 -0
  49. package/dist/integrations/slack/client.test.js.map +1 -0
  50. package/dist/integrations/slack/index.d.ts +2 -1
  51. package/dist/integrations/slack/index.d.ts.map +1 -1
  52. package/dist/integrations/slack/index.js +1 -0
  53. package/dist/integrations/slack/index.js.map +1 -1
  54. package/dist/integrations/slack/types.d.ts +127 -28
  55. package/dist/integrations/slack/types.d.ts.map +1 -1
  56. package/dist/integrations/slack/types.js +27 -1
  57. package/dist/integrations/slack/types.js.map +1 -1
  58. package/dist/integrations/snowflake/client.d.ts +2 -2
  59. package/dist/integrations/snowflake/client.js +2 -2
  60. package/dist/runtime/context.d.ts +1 -1
  61. package/dist/runtime/executor.d.ts +2 -2
  62. package/dist/types.d.ts +14 -5
  63. package/dist/types.d.ts.map +1 -1
  64. package/package.json +2 -2
  65. package/src/api/definition.test.ts +40 -15
  66. package/src/api/definition.ts +19 -12
  67. package/src/errors.ts +1 -1
  68. package/src/index.ts +13 -30
  69. package/src/integrations/asana/README.md +12 -12
  70. package/src/integrations/base/index.ts +2 -1
  71. package/src/integrations/base/rest-api-client-base.ts +134 -0
  72. package/src/integrations/base/rest-api-integration-client.ts +12 -89
  73. package/src/integrations/bitbucket/README.md +19 -19
  74. package/src/integrations/box/README.md +24 -24
  75. package/src/integrations/box/types.ts +1 -1
  76. package/src/integrations/circleci/README.md +18 -18
  77. package/src/integrations/declarations.ts +5 -91
  78. package/src/integrations/documentation.test.ts +0 -2
  79. package/src/integrations/googledrive/README.md +25 -22
  80. package/src/integrations/googledrive/types.ts +1 -1
  81. package/src/integrations/graphql/README.md +2 -2
  82. package/src/integrations/index.ts +0 -45
  83. package/src/integrations/registry.ts +1 -34
  84. package/src/integrations/salesforce/README.md +11 -9
  85. package/src/integrations/slack/README.md +62 -19
  86. package/src/integrations/slack/client.test.ts +553 -0
  87. package/src/integrations/slack/client.ts +92 -12
  88. package/src/integrations/slack/index.ts +6 -1
  89. package/src/integrations/slack/types.ts +142 -29
  90. package/src/integrations/snowflake/client.ts +2 -2
  91. package/src/integrations/zoom/README.md +15 -15
  92. package/src/runtime/context.ts +1 -1
  93. package/src/runtime/executor.ts +2 -2
  94. package/src/types.ts +14 -5
  95. package/dist/integrations/couchbase/client.d.ts +0 -36
  96. package/dist/integrations/couchbase/client.d.ts.map +0 -1
  97. package/dist/integrations/couchbase/client.js +0 -148
  98. package/dist/integrations/couchbase/client.js.map +0 -1
  99. package/dist/integrations/couchbase/index.d.ts +0 -8
  100. package/dist/integrations/couchbase/index.d.ts.map +0 -1
  101. package/dist/integrations/couchbase/index.js +0 -7
  102. package/dist/integrations/couchbase/index.js.map +0 -1
  103. package/dist/integrations/couchbase/types.d.ts +0 -100
  104. package/dist/integrations/couchbase/types.d.ts.map +0 -1
  105. package/dist/integrations/couchbase/types.js +0 -5
  106. package/dist/integrations/couchbase/types.js.map +0 -1
  107. package/dist/integrations/kafka/client.d.ts +0 -25
  108. package/dist/integrations/kafka/client.d.ts.map +0 -1
  109. package/dist/integrations/kafka/client.js +0 -124
  110. package/dist/integrations/kafka/client.js.map +0 -1
  111. package/dist/integrations/kafka/index.d.ts +0 -8
  112. package/dist/integrations/kafka/index.d.ts.map +0 -1
  113. package/dist/integrations/kafka/index.js +0 -7
  114. package/dist/integrations/kafka/index.js.map +0 -1
  115. package/dist/integrations/kafka/types.d.ts +0 -113
  116. package/dist/integrations/kafka/types.d.ts.map +0 -1
  117. package/dist/integrations/kafka/types.js +0 -5
  118. package/dist/integrations/kafka/types.js.map +0 -1
  119. package/dist/integrations/kinesis/client.d.ts +0 -31
  120. package/dist/integrations/kinesis/client.d.ts.map +0 -1
  121. package/dist/integrations/kinesis/client.js +0 -101
  122. package/dist/integrations/kinesis/client.js.map +0 -1
  123. package/dist/integrations/kinesis/index.d.ts +0 -8
  124. package/dist/integrations/kinesis/index.d.ts.map +0 -1
  125. package/dist/integrations/kinesis/index.js +0 -7
  126. package/dist/integrations/kinesis/index.js.map +0 -1
  127. package/dist/integrations/kinesis/types.d.ts +0 -97
  128. package/dist/integrations/kinesis/types.d.ts.map +0 -1
  129. package/dist/integrations/kinesis/types.js +0 -7
  130. package/dist/integrations/kinesis/types.js.map +0 -1
  131. package/dist/integrations/python/client.d.ts +0 -42
  132. package/dist/integrations/python/client.d.ts.map +0 -1
  133. package/dist/integrations/python/client.js +0 -89
  134. package/dist/integrations/python/client.js.map +0 -1
  135. package/dist/integrations/python/client.test.d.ts +0 -5
  136. package/dist/integrations/python/client.test.d.ts.map +0 -1
  137. package/dist/integrations/python/client.test.js +0 -214
  138. package/dist/integrations/python/client.test.js.map +0 -1
  139. package/dist/integrations/python/index.d.ts +0 -6
  140. package/dist/integrations/python/index.d.ts.map +0 -1
  141. package/dist/integrations/python/index.js +0 -5
  142. package/dist/integrations/python/index.js.map +0 -1
  143. package/dist/integrations/python/types.d.ts +0 -85
  144. package/dist/integrations/python/types.d.ts.map +0 -1
  145. package/dist/integrations/python/types.js +0 -5
  146. package/dist/integrations/python/types.js.map +0 -1
  147. package/src/integrations/couchbase/README.md +0 -138
  148. package/src/integrations/couchbase/client.ts +0 -225
  149. package/src/integrations/couchbase/index.ts +0 -8
  150. package/src/integrations/couchbase/types.ts +0 -126
  151. package/src/integrations/kafka/README.md +0 -144
  152. package/src/integrations/kafka/client.ts +0 -216
  153. package/src/integrations/kafka/index.ts +0 -14
  154. package/src/integrations/kafka/types.ts +0 -128
  155. package/src/integrations/kinesis/README.md +0 -153
  156. package/src/integrations/kinesis/client.ts +0 -146
  157. package/src/integrations/kinesis/index.ts +0 -14
  158. package/src/integrations/kinesis/types.ts +0 -114
  159. package/src/integrations/python/README.md +0 -566
  160. package/src/integrations/python/client.test.ts +0 -341
  161. package/src/integrations/python/client.ts +0 -136
  162. package/src/integrations/python/index.ts +0 -6
  163. package/src/integrations/python/types.ts +0 -92
@@ -1,50 +1,163 @@
1
1
  /**
2
2
  * Slack client types.
3
+ *
4
+ * Defines the SlackResponse<T> discriminated union that wraps every
5
+ * Slack API call, plus the SlackClient interface consumers interact with.
3
6
  */
4
7
 
8
+ import { z } from "zod";
9
+
5
10
  import type { BaseIntegrationClient } from "../../types.js";
6
- import type { SupportsApiRequest } from "../base/index.js";
11
+ import type { ApiRequestOptions, TraceMetadata } from "../base/types.js";
7
12
 
8
13
  /**
9
- * Slack client for API interactions.
14
+ * Zod schema for Slack API error responses.
15
+ *
16
+ * Slack returns errors as HTTP 200 with `{ ok: false, error: "..." }`.
17
+ * For `missing_scope` errors, `needed` and `provided` list the
18
+ * required vs current OAuth scopes.
19
+ */
20
+ export const SlackErrorSchema = z.object({
21
+ ok: z.literal(false),
22
+ error: z.string(),
23
+ needed: z.string().optional(),
24
+ provided: z.string().optional(),
25
+ });
26
+
27
+ /** Slack API error response, derived from {@link SlackErrorSchema}. */
28
+ export type SlackErrorResponse = z.infer<typeof SlackErrorSchema>;
29
+
30
+ /**
31
+ * Zod schema for Slack success envelopes.
32
+ *
33
+ * Success responses from Slack include `{ ok: true, ...payload }`.
34
+ * Callers provide schemas for the payload fields only; the SDK validates
35
+ * this envelope separately and injects `ok: true` in the returned type.
36
+ */
37
+ export const SlackSuccessEnvelopeSchema = z.object({
38
+ ok: z.literal(true),
39
+ });
40
+
41
+ /**
42
+ * Enforce that caller-provided success schemas do not define `ok`.
10
43
  *
11
- * Provides generic API request method for interacting with Slack's API.
12
- * Use apiRequest() to make calls to any Slack API endpoint.
44
+ * The `ok` field belongs to the Slack envelope and is injected by the SDK.
45
+ */
46
+ type SlackSuccessSchemaHasExplicitOkKey<TSchema extends z.AnyZodObject> =
47
+ TSchema extends z.ZodObject<
48
+ infer TShape,
49
+ z.UnknownKeysParam,
50
+ z.ZodTypeAny,
51
+ unknown,
52
+ unknown
53
+ >
54
+ ? "ok" extends keyof TShape
55
+ ? true
56
+ : false
57
+ : false;
58
+
59
+ export type SlackSuccessSchema<TSchema extends z.AnyZodObject> =
60
+ SlackSuccessSchemaHasExplicitOkKey<TSchema> extends true ? never : TSchema;
61
+
62
+ /**
63
+ * Schema configuration for Slack API requests.
64
+ *
65
+ * Response schema must be an object payload schema (without `ok`).
66
+ */
67
+ export interface SlackApiRequestSchema<
68
+ TBody,
69
+ TResponseSchema extends z.AnyZodObject,
70
+ > {
71
+ body?: z.ZodSchema<TBody>;
72
+ response: SlackSuccessSchema<TResponseSchema>;
73
+ }
74
+
75
+ /** Slack success response shape with injected discriminant. */
76
+ export type SlackSuccessResponse<T extends Record<string, unknown>> = T & {
77
+ readonly ok: true;
78
+ };
79
+
80
+ /**
81
+ * Discriminated union of a Slack success response and error response.
82
+ *
83
+ * On success (`ok: true`), the type is `T & { ok: true }` — the
84
+ * validated schema output intersected with a literal `true` discriminant.
85
+ * On failure (`ok: false`), the type is {@link SlackErrorResponse}.
86
+ *
87
+ * Use the `ok` field as a discriminant for type narrowing:
13
88
  *
14
89
  * @example
15
90
  * ```typescript
16
- * // Declare in api(): integrations: { slack: slack(INTEGRATION_ID) }
17
- * // In run(), access via: ctx.integrations.slack
18
- * await ctx.integrations.slack.apiRequest(
19
- * {
20
- * method: 'POST',
21
- * path: '/chat.postMessage',
22
- * body: {
23
- * channel: '#alerts',
24
- * text: 'Deployment completed!',
25
- * },
26
- * },
27
- * { response: PostMessageResponseSchema }
91
+ * const result = await ctx.integrations.slack.apiRequest(
92
+ * { method: "GET", path: "/conversations.list", params: { limit: 100 } },
93
+ * { response: ListChannelsSchema },
28
94
  * );
29
95
  *
30
- * // List channels
31
- * const ListChannelsResponseSchema = z.object({
32
- * channels: z.array(z.object({
33
- * id: z.string(),
34
- * name: z.string(),
35
- * })),
36
- * });
96
+ * if (!result.ok) {
97
+ * // TypeScript narrows to SlackErrorResponse
98
+ * console.error(`Slack error: ${result.error}`);
99
+ * return;
100
+ * }
37
101
  *
102
+ * // TypeScript narrows to T & { ok: true }
103
+ * result.channels.forEach(ch => console.log(ch.name));
104
+ * ```
105
+ */
106
+ export type SlackResponse<T extends Record<string, unknown>> =
107
+ | SlackSuccessResponse<T>
108
+ | SlackErrorResponse;
109
+
110
+ /**
111
+ * Slack client for API interactions.
112
+ *
113
+ * Returns {@link SlackResponse}<T> from `apiRequest` — a discriminated
114
+ * union that encapsulates both Slack success and error responses. This
115
+ * avoids confusing Zod validation errors when Slack returns `ok: false`
116
+ * (which is an HTTP 200 with no success-specific fields).
117
+ *
118
+ * Note: SlackClient intentionally does not extend `SupportsApiRequest`.
119
+ * `SupportsApiRequest.apiRequest` returns `Promise<TResponse>`, while
120
+ * Slack returns `Promise<SlackResponse<T>>` by design.
121
+ *
122
+ * @example
123
+ * ```typescript
38
124
  * const result = await ctx.integrations.slack.apiRequest(
39
125
  * {
40
- * method: 'GET',
41
- * path: '/conversations.list',
42
- * params: { limit: 100 },
126
+ * method: "POST",
127
+ * path: "/chat.postMessage",
128
+ * body: { channel: "#alerts", text: "Deployed!" },
43
129
  * },
44
- * { response: ListChannelsResponseSchema }
130
+ * { response: PostMessageResponseSchema },
45
131
  * );
132
+ *
133
+ * if (!result.ok) {
134
+ * throw new Error(`Slack API error: ${result.error}`);
135
+ * }
136
+ *
137
+ * console.log(`Message sent: ${result.ts}`);
46
138
  * ```
47
139
  */
48
- export interface SlackClient extends BaseIntegrationClient, SupportsApiRequest {
49
- // apiRequest() method inherited from SupportsApiRequest
140
+ export interface SlackClient extends BaseIntegrationClient {
141
+ /**
142
+ * Execute a Slack API request with type-safe response handling.
143
+ *
144
+ * Returns a {@link SlackResponse}<TResponse> discriminated union:
145
+ * - On success: the Zod-validated payload with injected `ok: true`
146
+ * - On failure: a {@link SlackErrorResponse} with `ok: false` and the Slack error code
147
+ *
148
+ * Body validation still throws {@link RestApiValidationError} if the
149
+ * request body fails its Zod schema.
150
+ *
151
+ * @param options - Request configuration (method, path, params, body, headers)
152
+ * @param schema - Zod schemas for body and response validation (response REQUIRED)
153
+ * - `response` must be `z.object(...)`
154
+ * - `response` should define payload fields only (MUST NOT define `ok`)
155
+ * @param metadata - Optional trace metadata for observability
156
+ * @returns Discriminated union — check `result.ok` before accessing fields
157
+ */
158
+ apiRequest<TBody, TResponseSchema extends z.AnyZodObject>(
159
+ options: ApiRequestOptions<TBody>,
160
+ schema: SlackApiRequestSchema<TBody, TResponseSchema>,
161
+ metadata?: TraceMetadata,
162
+ ): Promise<SlackResponse<z.output<TResponseSchema>>>;
50
163
  }
@@ -43,10 +43,10 @@ export class SnowflakeClientImpl
43
43
  * Builds a Snowflake request object from SQL and parameters.
44
44
  *
45
45
  * When params are provided, the SQL body is sent with placeholders intact
46
- * (e.g. $1, $2) and the parameter values are passed via the `parameters`
46
+ * (e.g. ?) and the parameter values are passed via the `parameters`
47
47
  * field as a JSON-stringified array for server-side binding.
48
48
  *
49
- * @param sql - The SQL query with optional $1, $2 placeholders
49
+ * @param sql - The SQL query with optional ? placeholders
50
50
  * @param params - Optional array of parameter values for server-side binding
51
51
  * @returns The plugin request object
52
52
  */
@@ -50,7 +50,7 @@ export default api({
50
50
  const result = await ctx.integrations.zoom.apiRequest(
51
51
  {
52
52
  method: "POST",
53
- path: "/v2/users/me/meetings",
53
+ path: "/users/me/meetings",
54
54
  body: {
55
55
  topic: topic,
56
56
  type: 2, // Scheduled meeting
@@ -99,7 +99,7 @@ const ListMeetingsResponseSchema = z.object({
99
99
  const result = await ctx.integrations.zoom.apiRequest(
100
100
  {
101
101
  method: "GET",
102
- path: "/v2/users/me/meetings",
102
+ path: "/users/me/meetings",
103
103
  params: {
104
104
  type: "scheduled", // upcoming, live, scheduled
105
105
  page_size: 30,
@@ -137,7 +137,7 @@ const MeetingDetailSchema = z.object({
137
137
  const result = await ctx.integrations.zoom.apiRequest(
138
138
  {
139
139
  method: "GET",
140
- path: `/v2/meetings/${meetingId}`,
140
+ path: `/meetings/${meetingId}`,
141
141
  },
142
142
  { response: MeetingDetailSchema },
143
143
  );
@@ -149,7 +149,7 @@ const result = await ctx.integrations.zoom.apiRequest(
149
149
  await ctx.integrations.zoom.apiRequest(
150
150
  {
151
151
  method: "PATCH",
152
- path: `/v2/meetings/${meetingId}`,
152
+ path: `/meetings/${meetingId}`,
153
153
  body: {
154
154
  topic: "Updated Meeting Topic",
155
155
  duration: 60,
@@ -168,7 +168,7 @@ await ctx.integrations.zoom.apiRequest(
168
168
  await ctx.integrations.zoom.apiRequest(
169
169
  {
170
170
  method: "DELETE",
171
- path: `/v2/meetings/${meetingId}`,
171
+ path: `/meetings/${meetingId}`,
172
172
  params: {
173
173
  schedule_for_reminder: true,
174
174
  },
@@ -196,7 +196,7 @@ const WebinarSchema = z.object({
196
196
  const result = await ctx.integrations.zoom.apiRequest(
197
197
  {
198
198
  method: "POST",
199
- path: "/v2/users/me/webinars",
199
+ path: "/users/me/webinars",
200
200
  body: {
201
201
  topic: "Product Launch Webinar",
202
202
  type: 5, // Scheduled webinar
@@ -234,7 +234,7 @@ const UserSchema = z.object({
234
234
  const result = await ctx.integrations.zoom.apiRequest(
235
235
  {
236
236
  method: "GET",
237
- path: "/v2/users/me",
237
+ path: "/users/me",
238
238
  },
239
239
  { response: UserSchema },
240
240
  );
@@ -265,7 +265,7 @@ const ListUsersResponseSchema = z.object({
265
265
  const result = await ctx.integrations.zoom.apiRequest(
266
266
  {
267
267
  method: "GET",
268
- path: "/v2/users",
268
+ path: "/users",
269
269
  params: {
270
270
  status: "active",
271
271
  page_size: 30,
@@ -289,7 +289,7 @@ const RegistrantSchema = z.object({
289
289
  const result = await ctx.integrations.zoom.apiRequest(
290
290
  {
291
291
  method: "POST",
292
- path: `/v2/meetings/${meetingId}/registrants`,
292
+ path: `/meetings/${meetingId}/registrants`,
293
293
  body: {
294
294
  email: "attendee@example.com",
295
295
  first_name: "John",
@@ -316,7 +316,7 @@ await zoom.listMeetings();
316
316
 
317
317
  // CORRECT - Use apiRequest
318
318
  await ctx.integrations.zoom.apiRequest(
319
- { method: "POST", path: "/v2/users/me/meetings", body: { ... } },
319
+ { method: "POST", path: "/users/me/meetings", body: { ... } },
320
320
  { response: MeetingSchema }
321
321
  );
322
322
  ```
@@ -346,10 +346,10 @@ Use "me" for the authenticated user:
346
346
 
347
347
  ```typescript
348
348
  // Current user's meetings
349
- const path = "/v2/users/me/meetings";
349
+ const path = "/users/me/meetings";
350
350
 
351
351
  // Specific user's meetings (requires admin scope)
352
- const path = `/v2/users/${userId}/meetings`;
352
+ const path = `/users/${userId}/meetings`;
353
353
  ```
354
354
 
355
355
  ### Date/Time Format
@@ -372,7 +372,7 @@ Many operations return empty responses:
372
372
  ```typescript
373
373
  // PATCH and DELETE often return 204 No Content
374
374
  await ctx.integrations.zoom.apiRequest(
375
- { method: "PATCH", path: `/v2/meetings/${id}`, body: { ... } },
375
+ { method: "PATCH", path: `/meetings/${id}`, body: { ... } },
376
376
  { response: z.object({}).optional() } // Handle empty response
377
377
  );
378
378
  ```
@@ -415,7 +415,7 @@ async function getAllMeetings(zoom: ZoomClient) {
415
415
  const result = await ctx.integrations.zoom.apiRequest(
416
416
  {
417
417
  method: "GET",
418
- path: "/v2/users/me/meetings",
418
+ path: "/users/me/meetings",
419
419
  params: {
420
420
  page_size: 300,
421
421
  page_number: pageNumber,
@@ -441,7 +441,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
441
441
 
442
442
  try {
443
443
  const result = await ctx.integrations.zoom.apiRequest(
444
- { method: "POST", path: "/v2/users/me/meetings", body: { ... } },
444
+ { method: "POST", path: "/users/me/meetings", body: { ... } },
445
445
  { response: MeetingSchema }
446
446
  );
447
447
  } catch (error) {
@@ -41,7 +41,7 @@ export interface CreateContextOptions {
41
41
  /**
42
42
  * Function to execute integration operations.
43
43
  *
44
- * For language plugins (Python, JavaScript), pass the bindings parameter
44
+ * For language plugins (JavaScript), pass the bindings parameter
45
45
  * to the API execution request as `input` field for binding resolution.
46
46
  */
47
47
  executeQuery: (
@@ -46,13 +46,13 @@ export interface ExecuteApiRequest {
46
46
  * The request object should match the protobuf Plugin schema for the
47
47
  * specific integration type (e.g., postgresql.v1.Plugin for Postgres).
48
48
  *
49
- * For language plugins (Python, JavaScript), the bindings parameter should be
49
+ * For language plugins (JavaScript), the bindings parameter should be
50
50
  * passed to the API execution request as `input` or `inputs` field for
51
51
  * binding resolution.
52
52
  *
53
53
  * @param integrationId - The integration ID
54
54
  * @param request - Plugin-specific request object matching the proto schema
55
- * @param bindings - Optional bindings data for binding resolution (e.g., Python/JavaScript bindings)
55
+ * @param bindings - Optional bindings data for binding resolution (e.g., JavaScript bindings)
56
56
  * @returns Promise resolving to the operation result
57
57
  */
58
58
  executeQuery: (
package/src/types.ts CHANGED
@@ -44,10 +44,13 @@ import type {
44
44
  * if (users.length === 0) {
45
45
  * throw new Error('User not found');
46
46
  * }
47
- * await ctx.integrations.notifier.postMessage({
48
- * channel: '#alerts',
49
- * text: `Fetched user ${users[0].name}`,
50
- * });
47
+ * const notifyResult = await ctx.integrations.notifier.apiRequest(
48
+ * { method: 'POST', path: '/chat.postMessage', body: { channel: '#alerts', text: `Fetched user ${users[0].name}` } },
49
+ * { response: z.object({ channel: z.string(), ts: z.string() }) }
50
+ * );
51
+ * if (!notifyResult.ok) {
52
+ * throw new Error(`Slack API error: ${notifyResult.error}`);
53
+ * }
51
54
  * return { user: users[0] };
52
55
  * },
53
56
  * });
@@ -162,7 +165,13 @@ export interface ApiContext<
162
165
  * const users = await ctx.integrations.db.query('SELECT * FROM users', UserSchema);
163
166
  *
164
167
  * // ctx.integrations.notifier is SlackClient
165
- * await ctx.integrations.notifier.postMessage({ channel: '#alerts', text: 'Hello!' });
168
+ * const notifyResult = await ctx.integrations.notifier.apiRequest(
169
+ * { method: 'POST', path: '/chat.postMessage', body: { channel: '#alerts', text: 'Hello!' } },
170
+ * { response: z.object({ channel: z.string(), ts: z.string() }) }
171
+ * );
172
+ * if (!notifyResult.ok) {
173
+ * throw new Error(`Slack API error: ${notifyResult.error}`);
174
+ * }
166
175
  * ```
167
176
  */
168
177
  readonly integrations: IntegrationsMap<TIntegrations>;
@@ -1,36 +0,0 @@
1
- /**
2
- * Couchbase client implementation.
3
- *
4
- * Builds proto JSON-style request objects for SQL++ queries, document insert,
5
- * get, and remove operations against Couchbase buckets.
6
- *
7
- * IMPORTANT: Request objects use plain objects with flat proto JSON keys
8
- * (e.g. `{runSql: {sqlBody}}`) rather than the protobuf-es `CouchbaseRequest`
9
- * type. The protobuf-es type uses oneof wrappers (`{case: "runSql", value: {...}}`)
10
- * which get lost during the JSON → Go proto → JSON roundtrip in the orchestrator,
11
- * resulting in "invalid operation: undefined". The Go orchestrator expects the
12
- * standard proto JSON format with flat field names, not the TS-specific wrapper.
13
- */
14
- import type { z } from "zod";
15
- import type { QueryExecutor, TraceMetadata } from "../registry.js";
16
- import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
17
- import type { CouchbaseClient, CouchbaseIdentifier } from "./types.js";
18
- /**
19
- * Internal implementation of CouchbaseClient.
20
- *
21
- * Communicates with the orchestrator using the native Couchbase plugin
22
- * proto format, supporting SQL++ queries and key-value document operations.
23
- * All operations require a bucket name.
24
- */
25
- export declare class CouchbaseClientImpl implements CouchbaseClient, IntegrationClientImpl {
26
- readonly config: IntegrationConfig;
27
- private readonly executeQuery;
28
- constructor(config: IntegrationConfig, executeQuery: QueryExecutor);
29
- get name(): string;
30
- get pluginId(): string;
31
- query<T>(bucket: string, sql: string, schema: z.ZodSchema<T>, params?: unknown[], metadata?: TraceMetadata): Promise<T[]>;
32
- insert(key: string, value: unknown, identifier: CouchbaseIdentifier, metadata?: TraceMetadata): Promise<void>;
33
- get<T>(key: string, schema: z.ZodSchema<T>, identifier: CouchbaseIdentifier, metadata?: TraceMetadata): Promise<T>;
34
- remove(key: string, identifier: CouchbaseIdentifier, metadata?: TraceMetadata): Promise<void>;
35
- }
36
- //# sourceMappingURL=client.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/integrations/couchbase/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;;GAMG;AACH,qBAAa,mBACX,YAAW,eAAe,EAAE,qBAAqB;IAEjD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;gBAEjC,MAAM,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa;IAKlE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAEK,KAAK,CAAC,CAAC,EACX,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC;IAyDT,MAAM,CACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,IAAI,CAAC;IA4BV,GAAG,CAAC,CAAC,EACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,CAAC,CAAC;IA4CP,MAAM,CACV,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,IAAI,CAAC;CA0BjB"}
@@ -1,148 +0,0 @@
1
- /**
2
- * Couchbase client implementation.
3
- *
4
- * Builds proto JSON-style request objects for SQL++ queries, document insert,
5
- * get, and remove operations against Couchbase buckets.
6
- *
7
- * IMPORTANT: Request objects use plain objects with flat proto JSON keys
8
- * (e.g. `{runSql: {sqlBody}}`) rather than the protobuf-es `CouchbaseRequest`
9
- * type. The protobuf-es type uses oneof wrappers (`{case: "runSql", value: {...}}`)
10
- * which get lost during the JSON → Go proto → JSON roundtrip in the orchestrator,
11
- * resulting in "invalid operation: undefined". The Go orchestrator expects the
12
- * standard proto JSON format with flat field names, not the TS-specific wrapper.
13
- */
14
- import { QueryValidationError, RestApiValidationError } from "../../errors.js";
15
- import { IntegrationError } from "../../runtime/errors.js";
16
- import { describeType } from "../utils.js";
17
- /**
18
- * Internal implementation of CouchbaseClient.
19
- *
20
- * Communicates with the orchestrator using the native Couchbase plugin
21
- * proto format, supporting SQL++ queries and key-value document operations.
22
- * All operations require a bucket name.
23
- */
24
- export class CouchbaseClientImpl {
25
- config;
26
- executeQuery;
27
- constructor(config, executeQuery) {
28
- this.config = config;
29
- this.executeQuery = executeQuery;
30
- }
31
- get name() {
32
- return this.config.name;
33
- }
34
- get pluginId() {
35
- return this.config.pluginId;
36
- }
37
- async query(bucket, sql, schema, params, metadata) {
38
- const hasParams = params && params.length > 0;
39
- const request = {
40
- bucketName: bucket,
41
- runSql: {
42
- sqlBody: sql,
43
- parameters: hasParams ? JSON.stringify(params) : undefined,
44
- },
45
- };
46
- try {
47
- const result = await this.executeQuery(request, undefined, metadata);
48
- if (!Array.isArray(result)) {
49
- throw new IntegrationError(this.config.name, "query", `Expected array result from Couchbase query, got: ${describeType(result)}`);
50
- }
51
- const validated = [];
52
- for (let i = 0; i < result.length; i++) {
53
- const row = result[i];
54
- const parseResult = schema.safeParse(row);
55
- if (!parseResult.success) {
56
- throw new QueryValidationError(`Row ${i} failed validation: ${parseResult.error.message}`, {
57
- rowIndex: i,
58
- errors: parseResult.error.errors,
59
- row,
60
- });
61
- }
62
- validated.push(parseResult.data);
63
- }
64
- return validated;
65
- }
66
- catch (error) {
67
- if (error instanceof QueryValidationError ||
68
- error instanceof IntegrationError) {
69
- throw error;
70
- }
71
- throw new IntegrationError(this.config.name, "query", error);
72
- }
73
- }
74
- async insert(key, value, identifier, metadata) {
75
- const request = {
76
- bucketName: identifier.bucket,
77
- insert: {
78
- key,
79
- value: typeof value === "string" ? value : JSON.stringify(value),
80
- identifier: {
81
- scope: identifier.scope,
82
- collection: identifier.collection,
83
- },
84
- },
85
- };
86
- try {
87
- await this.executeQuery(request, undefined, metadata);
88
- }
89
- catch (error) {
90
- if (error instanceof IntegrationError) {
91
- throw error;
92
- }
93
- throw new IntegrationError(this.config.name, "insert", error);
94
- }
95
- }
96
- async get(key, schema, identifier, metadata) {
97
- const request = {
98
- bucketName: identifier.bucket,
99
- get: {
100
- key,
101
- identifier: {
102
- scope: identifier.scope,
103
- collection: identifier.collection,
104
- },
105
- },
106
- };
107
- try {
108
- const result = await this.executeQuery(request, undefined, metadata);
109
- const parseResult = schema.safeParse(result);
110
- if (!parseResult.success) {
111
- throw new RestApiValidationError(`Result validation failed: ${parseResult.error.message}`, {
112
- zodError: parseResult.error,
113
- data: result,
114
- });
115
- }
116
- return parseResult.data;
117
- }
118
- catch (error) {
119
- if (error instanceof RestApiValidationError ||
120
- error instanceof IntegrationError) {
121
- throw error;
122
- }
123
- throw new IntegrationError(this.config.name, "get", error);
124
- }
125
- }
126
- async remove(key, identifier, metadata) {
127
- const request = {
128
- bucketName: identifier.bucket,
129
- remove: {
130
- key,
131
- identifier: {
132
- scope: identifier.scope,
133
- collection: identifier.collection,
134
- },
135
- },
136
- };
137
- try {
138
- await this.executeQuery(request, undefined, metadata);
139
- }
140
- catch (error) {
141
- if (error instanceof IntegrationError) {
142
- throw error;
143
- }
144
- throw new IntegrationError(this.config.name, "remove", error);
145
- }
146
- }
147
- }
148
- //# sourceMappingURL=client.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/integrations/couchbase/client.ts"],"names":[],"mappings":"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"}
@@ -1,8 +0,0 @@
1
- /**
2
- * Couchbase integration client.
3
- *
4
- * @module
5
- */
6
- export type { CouchbaseClient, CouchbaseIdentifier } from "./types.js";
7
- export { CouchbaseClientImpl } from "./client.js";
8
- //# sourceMappingURL=index.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/integrations/couchbase/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
@@ -1,7 +0,0 @@
1
- /**
2
- * Couchbase integration client.
3
- *
4
- * @module
5
- */
6
- export { CouchbaseClientImpl } from "./client.js";
7
- //# sourceMappingURL=index.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/integrations/couchbase/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}