@superdurable/connector-klaviyo 0.1.0 → 0.1.1

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.
package/README.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # Klaviyo connector for TypeScript
2
2
 
3
- Install with `npm install @superdurable/connector-klaviyo@0.1.0`. This package implements `getProfile` and `createEvent` with generated operation-specific Step factories and the Go connector's branches.
3
+ Install with `npm install @superdurable/connector-klaviyo@0.1.1`. This package implements `getProfile` and `createEvent` with generated operation-specific Step factories and the Go connector's branches.
4
4
 
5
5
  | Operation | Factory | Happy branch | Optional branches |
6
6
  | --- | --- | --- | --- |
7
7
  | `getProfile` | `newGetProfileStep` | `found` | `notFound`, `providerRejected`, `invalidResponse`, `defect` |
8
8
  | `createEvent` | `newCreateEventStep` | `accepted` | `providerRejected`, `defect` |
9
9
 
10
- `createEvent` hashes Dex's stable call ID into the Klaviyo `unique_id`; retries use the same ID. HTTP 202 confirms acceptance for asynchronous processing. Both operations retry transport failures, 408, 409, 429, and 5xx. Missing or invalid credentials select `defect`; 401 and 403 select `providerRejected`.
10
+ `createEvent` hashes Dex's stable call ID into the Klaviyo `unique_id`; retries use the same ID. HTTP 202 confirms acceptance for asynchronous processing. Both operations retry transport failures, 408, 409, 429, and 5xx; `createEvent` also retries every status other than 202 and a definite refusal (400, 401, 403, 404, 411, 413, 414, 415, 422). Missing, invalid, or malformed stored credentials select `defect`; 401 and 403 select `providerRejected`.
11
11
 
12
12
  `getProfile` treats the profile ID as an opaque URL path segment. It percent-encodes punctuation such as commas, semicolons, and exclamation marks before sending the request.
13
13
 
@@ -1,16 +1,18 @@
1
1
  {
2
2
  "connectorId": "klaviyo",
3
- "releaseTag": "connectors/klaviyo/go/v0.2.0",
3
+ "releaseTag": "connectors/klaviyo/go/v0.2.1",
4
4
  "package": {
5
5
  "ecosystem": "npm",
6
6
  "name": "@superdurable/connector-klaviyo",
7
- "version": "0.1.0"
7
+ "version": "0.1.1"
8
8
  },
9
9
  "factories": [
10
10
  {
11
11
  "name": "newGetProfileStep",
12
12
  "kind": "query",
13
13
  "operationId": "getProfile",
14
+ "inputType": "GetProfileInput",
15
+ "description": "Get one profile by Klaviyo ID.",
14
16
  "fields": {
15
17
  "stepType": "stepType",
16
18
  "annotations": "annotations",
@@ -43,12 +45,28 @@
43
45
  "field": "defect",
44
46
  "optional": true
45
47
  }
46
- ]
48
+ ],
49
+ "inputSchema": {
50
+ "additionalProperties": false,
51
+ "description": "GetProfileInput identifies a Klaviyo profile.",
52
+ "properties": {
53
+ "id": {
54
+ "description": "ID is Klaviyo's opaque profile ID.",
55
+ "type": "string"
56
+ }
57
+ },
58
+ "required": [
59
+ "id"
60
+ ],
61
+ "type": "object"
62
+ }
47
63
  },
48
64
  {
49
65
  "name": "newCreateEventStep",
50
66
  "kind": "mutation",
51
67
  "operationId": "createEvent",
68
+ "inputType": "CreateEventInput",
69
+ "description": "Submit a profile event with a unique_id derived from Dex's stable call identity.",
52
70
  "fields": {
53
71
  "stepType": "stepType",
54
72
  "annotations": "annotations",
@@ -71,7 +89,33 @@
71
89
  "field": "defect",
72
90
  "optional": true
73
91
  }
74
- ]
92
+ ],
93
+ "inputSchema": {
94
+ "additionalProperties": false,
95
+ "description": "CreateEventInput associates one event with a profile email and metric.",
96
+ "properties": {
97
+ "email": {
98
+ "description": "Email identifies the profile. Klaviyo silently drops some test-domain events after accepting them.",
99
+ "type": "string"
100
+ },
101
+ "metricName": {
102
+ "description": "MetricName names the event metric.",
103
+ "type": "string"
104
+ },
105
+ "properties": {
106
+ "additionalProperties": {
107
+ "type": "string"
108
+ },
109
+ "description": "Properties contains optional non-secret string event properties.",
110
+ "type": "object"
111
+ }
112
+ },
113
+ "required": [
114
+ "email",
115
+ "metricName"
116
+ ],
117
+ "type": "object"
118
+ }
75
119
  }
76
120
  ]
77
121
  }
@@ -1,10 +1,36 @@
1
1
  // src/generated/models.ts
2
2
  import { z } from "zod";
3
+ import { SecretString } from "@superdurable/connectors-sdk";
3
4
  var ConfigSchema = z.object({
4
5
  "baseUrl": z.string().optional(),
5
6
  "timeoutMs": z.number().int().optional(),
6
7
  "maxResponseBytes": z.number().int().optional()
7
8
  });
9
+ var CredentialMaterialError = class extends TypeError {
10
+ constructor(message) {
11
+ super(message);
12
+ this.name = "CredentialMaterialError";
13
+ }
14
+ };
15
+ var sdkCredentialDecodingFailureMessages = /* @__PURE__ */ new Set([
16
+ "project credential decoding failed",
17
+ "shared project credential decoding failed",
18
+ "project credential decoding failed: this connector version does not support shared credentials"
19
+ ]);
20
+ function isCredentialMaterialError(error) {
21
+ return error instanceof CredentialMaterialError || error instanceof TypeError && sdkCredentialDecodingFailureMessages.has(error.message);
22
+ }
23
+ function decodeCredentials(value) {
24
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new CredentialMaterialError("credential fields are invalid");
25
+ const fields = value;
26
+ const allowed = /* @__PURE__ */ new Set(["private_api_key"]);
27
+ if (Object.keys(fields).some((key) => !allowed.has(key))) throw new CredentialMaterialError("stored credential does not match the connector credential fields");
28
+ if (fields["private_api_key"] != null && !(typeof fields["private_api_key"] === "string")) throw new CredentialMaterialError("credential private_api_key has an invalid type");
29
+ const credentials = {};
30
+ if (!fields["private_api_key"]) throw new CredentialMaterialError("credential private_api_key is required");
31
+ credentials.privateApiKey = new SecretString(fields["private_api_key"] ?? "");
32
+ return credentials;
33
+ }
8
34
  var GetProfileInputSchema = z.strictObject({
9
35
  "id": z.string()
10
36
  });
@@ -99,6 +125,9 @@ function newProjectConnection(project, connectionName, createClient) {
99
125
 
100
126
  export {
101
127
  ConfigSchema,
128
+ CredentialMaterialError,
129
+ isCredentialMaterialError,
130
+ decodeCredentials,
102
131
  GetProfileInputSchema,
103
132
  ProfileSchema,
104
133
  CreateEventInputSchema,
@@ -21,6 +21,14 @@ interface Credentials {
21
21
  /** Secret Klaviyo private API key starting pk_ from https://www.klaviyo.com/settings/account/api-keys after Settings > API keys > Create Private API Key; grant profiles:read and events:write. Blank prevents requests. */
22
22
  privateApiKey: SecretString;
23
23
  }
24
+ /** Stored credential material that fails the connector credential checks, so no retry can succeed. */
25
+ declare class CredentialMaterialError extends TypeError {
26
+ constructor(message: string);
27
+ }
28
+ /** Report malformed stored credential material, also behind the SDK provider's decoding TypeError. */
29
+ declare function isCredentialMaterialError(error: unknown): boolean;
30
+ /** Decode private credential fields for the connector. */
31
+ declare function decodeCredentials(value: unknown): Credentials;
24
32
  /** Host-owned source of private connector credentials. */
25
33
  type CredentialSource = CredentialProvider<Credentials>;
26
34
  /** GetProfileInput identifies a Klaviyo profile. */
@@ -92,4 +100,4 @@ declare function newConnection(client: Operations, reference: ConnectionRef): Co
92
100
  /** Bind scripted operations to a named connection. */
93
101
  declare function newConnectionWithOperations(operations: Operations, reference: ConnectionRef): Connection;
94
102
 
95
- export { type CreateEventInput as C, type EventAcceptance as E, type GetProfileInput as G, type Operations as O, type Profile as P, Connection as a, type Config as b, type Credentials as c, ConfigSchema as d, CreateEventInputSchema as e, type CredentialSource as f, EventAcceptanceSchema as g, GetProfileInputSchema as h, ProfileSchema as i, newConnectionWithOperations as j, newConnection as n };
103
+ export { type CreateEventInput as C, type EventAcceptance as E, type GetProfileInput as G, type Operations as O, type Profile as P, Connection as a, type Config as b, type Credentials as c, ConfigSchema as d, CreateEventInputSchema as e, CredentialMaterialError as f, type CredentialSource as g, EventAcceptanceSchema as h, GetProfileInputSchema as i, ProfileSchema as j, decodeCredentials as k, isCredentialMaterialError as l, newConnectionWithOperations as m, newConnection as n };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { C as CreateEventInput, E as EventAcceptance, a as Connection, G as GetProfileInput, P as Profile, O as Operations, b as Config, c as Credentials } from './connection-DmctBEyp.js';
2
- export { d as ConfigSchema, e as CreateEventInputSchema, f as CredentialSource, g as EventAcceptanceSchema, h as GetProfileInputSchema, i as ProfileSchema, n as newConnection, j as newConnectionWithOperations } from './connection-DmctBEyp.js';
1
+ import { C as CreateEventInput, E as EventAcceptance, a as Connection, G as GetProfileInput, P as Profile, O as Operations, b as Config, c as Credentials } from './connection-BvS1Rfu-.js';
2
+ export { d as ConfigSchema, e as CreateEventInputSchema, f as CredentialMaterialError, g as CredentialSource, h as EventAcceptanceSchema, i as GetProfileInputSchema, j as ProfileSchema, k as decodeCredentials, l as isCredentialMaterialError, n as newConnection, m as newConnectionWithOperations } from './connection-BvS1Rfu-.js';
3
3
  import * as _superdurable_connectors_sdk from '@superdurable/connectors-sdk';
4
4
  import { MutationDefinition, QueryDefinition, MutationStepConfig, Mutation, MutationResult, QueryStepConfig, Query, QueryResult, MutationStep, QueryStep, Call, QueryAttempt, MutationAttempt, CredentialProvider } from '@superdurable/connectors-sdk';
5
5
  import { StepTarget } from '@superdurable/dex';
package/dist/index.js CHANGED
@@ -9,6 +9,7 @@ import {
9
9
  CreateEventDefinition,
10
10
  CreateEventInputSchema,
11
11
  CreateEventMetadata,
12
+ CredentialMaterialError,
12
13
  EventAcceptanceSchema,
13
14
  GetProfileBranch,
14
15
  GetProfileBranchDefect,
@@ -21,10 +22,12 @@ import {
21
22
  GetProfileMetadata,
22
23
  ProfileSchema,
23
24
  ProviderID,
25
+ decodeCredentials,
26
+ isCredentialMaterialError,
24
27
  newConnection,
25
28
  newConnectionWithOperations,
26
29
  newProjectConnection
27
- } from "./chunk-VRCLTH4K.js";
30
+ } from "./chunk-GC6YRQKN.js";
28
31
 
29
32
  // src/generated/steps.ts
30
33
  import { goToBranch, newMutationStep, newQueryStep } from "@superdurable/connectors-sdk";
@@ -51,11 +54,13 @@ function newCreateEventStep(configuration) {
51
54
 
52
55
  // src/project.ts
53
56
  import { SecretString as SecretString2 } from "@superdurable/connectors-sdk";
54
- import { z } from "zod";
57
+ import { z as z2 } from "zod";
55
58
 
56
59
  // src/client.ts
57
60
  import { isHeaderSafeCredential, sendProviderRequest, validateBaseURL } from "@superdurable/connectors-sdk/providerhttp";
58
- import { SecretString } from "@superdurable/connectors-sdk";
61
+ import { ReauthorizationRequiredError, SecretString } from "@superdurable/connectors-sdk";
62
+ import { ConnectionNotSelectedError, CredentialBrokerRejectedError, ObjectNotFoundError } from "@superdurable/connectors-sdk/projectconfig";
63
+ import { z } from "zod";
59
64
 
60
65
  // src/operations.ts
61
66
  import { createHash } from "crypto";
@@ -106,6 +111,7 @@ var GetProfileOperation = class {
106
111
  try {
107
112
  response = await this.client.request(call, "GET", `/profiles/${pathEscape(input.id)}`);
108
113
  } catch (error) {
114
+ if (error instanceof UnavailableKlaviyoCredentialError) return newQueryRetry(failure("getProfile", "AVAILABILITY", error.message));
109
115
  if (error instanceof InvalidKlaviyoCredentialError) return queryFailure("defect", "AUTHENTICATION", "Klaviyo credentials are unavailable or invalid");
110
116
  if (error instanceof BodyTooLargeError && error.status !== void 0) {
111
117
  if (isRetryStatus(error.status)) return newQueryRetry(failure("getProfile", "AVAILABILITY", "Klaviyo profile lookup is temporarily unavailable"), parseRetryAfter(retryHeader(error.headers ?? {}), this.client.now()));
@@ -153,19 +159,25 @@ var CreateEventOperation = class {
153
159
  try {
154
160
  response = await this.client.request(call, "POST", "/events", payload);
155
161
  } catch (error) {
162
+ if (error instanceof UnavailableKlaviyoCredentialError) return newMutationRetry(failure("createEvent", "AVAILABILITY", `${error.message}; nothing was sent`));
156
163
  if (error instanceof InvalidKlaviyoCredentialError) return mutationFailure("defect", "AUTHENTICATION", "Klaviyo credentials are unavailable or invalid");
157
164
  if (error instanceof BodyTooLargeError && error.status !== void 0) {
158
165
  if (isRetryStatus(error.status)) return newMutationRetry(failure("createEvent", "AVAILABILITY", "Klaviyo event submission is temporarily unavailable"), parseRetryAfter(retryHeader(error.headers ?? {}), this.client.now()));
159
166
  if (error.status === 202) return newMutationBranch("accepted", { accepted: true });
160
- return mutationFailure("providerRejected", rejectionKind(error.status), `Klaviyo rejected event submission with HTTP ${error.status}`);
167
+ return unknownEventOutcome(error.status);
161
168
  }
162
169
  return newMutationRetry(failure("createEvent", "TRANSPORT", "Klaviyo event response is unavailable"));
163
170
  }
164
171
  if (isRetryStatus(response.status)) return newMutationRetry(failure("createEvent", "AVAILABILITY", "Klaviyo event submission is temporarily unavailable"), parseRetryAfter(retryHeader(response.headers), this.client.now()));
165
- if (response.status !== 202) return mutationFailure("providerRejected", rejectionKind(response.status), `Klaviyo rejected event submission with HTTP ${response.status}`);
166
- return newMutationBranch("accepted", { accepted: true });
172
+ if (response.status === 202) return newMutationBranch("accepted", { accepted: true });
173
+ if (!definiteRefusalStatuses.has(response.status)) return unknownEventOutcome(response.status);
174
+ return mutationFailure("providerRejected", rejectionKind(response.status), `Klaviyo rejected event submission with HTTP ${response.status}`);
167
175
  }
168
176
  };
177
+ var definiteRefusalStatuses = /* @__PURE__ */ new Set([400, 401, 403, 404, 411, 413, 414, 415, 422]);
178
+ function unknownEventOutcome(status) {
179
+ return newMutationRetry(failure("createEvent", "AVAILABILITY", `Klaviyo answered event submission with HTTP ${status}, so its outcome is unknown`));
180
+ }
169
181
 
170
182
  // src/client.ts
171
183
  var defaultBaseUrl = "https://a.klaviyo.com/api";
@@ -200,8 +212,8 @@ var KlaviyoClient = class {
200
212
  let credentials;
201
213
  try {
202
214
  credentials = await this.credentials.resolve(call, call.context.cancellationSignal);
203
- } catch {
204
- throw new InvalidKlaviyoCredentialError();
215
+ } catch (error) {
216
+ throw isTerminalCredentialError(error) ? new InvalidKlaviyoCredentialError() : new UnavailableKlaviyoCredentialError();
205
217
  }
206
218
  if (!(credentials.privateApiKey instanceof SecretString) || !isHeaderSafeCredential(credentials.privateApiKey.reveal())) throw new InvalidKlaviyoCredentialError();
207
219
  const request = {
@@ -223,19 +235,28 @@ var InvalidKlaviyoCredentialError = class extends Error {
223
235
  super("Klaviyo credentials are unavailable or invalid");
224
236
  }
225
237
  };
238
+ var UnavailableKlaviyoCredentialError = class extends Error {
239
+ /** Construct a secret-safe transient credential error. */
240
+ constructor() {
241
+ super("Klaviyo credentials are temporarily unavailable");
242
+ }
243
+ };
244
+ function isTerminalCredentialError(error) {
245
+ return error instanceof ReauthorizationRequiredError || error instanceof ObjectNotFoundError || error instanceof ConnectionNotSelectedError || error instanceof CredentialBrokerRejectedError || error instanceof z.ZodError || isCredentialMaterialError(error);
246
+ }
226
247
 
227
248
  // src/project.ts
228
249
  function newProjectConnection2(project, connectionName) {
229
250
  return newProjectConnection(project, connectionName, (loadedProject, name) => {
230
251
  const selected = loadedProject.configuration.connections.find((entry) => entry.connectorId === "klaviyo" && entry.connectionName === name);
231
252
  if (!selected) throw new TypeError("Klaviyo project connection is not configured");
232
- const config = z.object({ baseUrl: z.string().optional(), timeout: z.union([z.string(), z.number().int()]).optional(), maxResponseBytes: z.number().int().optional() }).parse(selected.configuration);
253
+ const config = z2.object({ baseUrl: z2.string().optional(), timeout: z2.union([z2.string(), z2.number().int()]).optional(), maxResponseBytes: z2.number().int().optional() }).parse(selected.configuration);
233
254
  const timeoutMs = typeof config.timeout === "number" ? Math.ceil(config.timeout / 1e6) : config.timeout ? parseDurationMilliseconds(config.timeout) : void 0;
234
255
  const clientConfig = { ...config.baseUrl !== void 0 ? { baseUrl: config.baseUrl } : {}, ...timeoutMs !== void 0 ? { timeoutMs } : {}, ...config.maxResponseBytes !== void 0 ? { maxResponseBytes: config.maxResponseBytes } : {} };
235
256
  const credentials = {
236
257
  async resolve(_call, signal) {
237
258
  const fields = await loadedProject.resolveCredential("klaviyo", name, signal);
238
- const decoded = z.object({ private_api_key: z.string().min(1) }).parse(fields);
259
+ const decoded = z2.object({ private_api_key: z2.string().min(1) }).parse(fields);
239
260
  return { privateApiKey: new SecretString2(decoded.private_api_key) };
240
261
  }
241
262
  };
@@ -267,6 +288,7 @@ export {
267
288
  CreateEventInputSchema,
268
289
  CreateEventMetadata,
269
290
  CreateEventOperation,
291
+ CredentialMaterialError,
270
292
  EventAcceptanceSchema,
271
293
  GetProfileBranch,
272
294
  GetProfileBranchDefect,
@@ -281,6 +303,8 @@ export {
281
303
  KlaviyoClient,
282
304
  ProfileSchema,
283
305
  ProviderID,
306
+ decodeCredentials,
307
+ isCredentialMaterialError,
284
308
  newConnection,
285
309
  newConnectionWithOperations,
286
310
  newCreateEventStep,
package/dist/mock.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { MockQuery, MockMutation, Case } from '@superdurable/connectors-sdk/connectormock';
2
2
  import { Failure } from '@superdurable/connectors-sdk';
3
- import { O as Operations, a as Connection, G as GetProfileInput, P as Profile, C as CreateEventInput, E as EventAcceptance } from './connection-DmctBEyp.js';
3
+ import { O as Operations, a as Connection, G as GetProfileInput, P as Profile, C as CreateEventInput, E as EventAcceptance } from './connection-BvS1Rfu-.js';
4
4
  import 'zod';
5
5
 
6
6
  /** Go zero value for GetProfileInput in scripted cases. */
package/dist/mock.js CHANGED
@@ -7,7 +7,7 @@ import {
7
7
  ProfileSchema,
8
8
  ProviderID,
9
9
  newConnectionWithOperations
10
- } from "./chunk-VRCLTH4K.js";
10
+ } from "./chunk-GC6YRQKN.js";
11
11
 
12
12
  // src/generated/mock.ts
13
13
  import { branchCase, retryCase, newMutation, newQuery } from "@superdurable/connectors-sdk/connectormock";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@superdurable/connector-klaviyo",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Klaviyo profile and event operations for Dex Flows",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -26,7 +26,8 @@
26
26
  "./mock": {
27
27
  "types": "./dist/mock.d.ts",
28
28
  "import": "./dist/mock.js"
29
- }
29
+ },
30
+ "./dex-connector.json": "./dex-connector.json"
30
31
  },
31
32
  "files": [
32
33
  "dist",