@superdurable/connector-fiftyonetracking 0.0.0-stage → 0.1.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Super Durable
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,5 @@
1
- # Temporary Holding Version
1
+ # 51Tracking TypeScript connector
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Read aggregate registered parcel counts by delivery status without exposing tracking numbers.
4
+
5
+ Install `@superdurable/connector-fiftyonetracking` and use `newProjectConnection` with the static connection name in the runnable [`examples/basic`](examples/basic) Flow. Configure the connection and provider credentials in Dex Web Connections. The operation `getShipmentStatusCounts` resolves credentials for each call. Local conformance tests replay the Go provider scenarios; live provider authorization has not been verified.
@@ -0,0 +1,52 @@
1
+ {
2
+ "connectorId": "fiftyonetracking",
3
+ "releaseTag": "connectors/fiftyonetracking/go/v0.1.0",
4
+ "package": {
5
+ "ecosystem": "npm",
6
+ "name": "@superdurable/connector-fiftyonetracking",
7
+ "version": "0.1.0"
8
+ },
9
+ "factories": [
10
+ {
11
+ "name": "newGetShipmentStatusCountsStep",
12
+ "kind": "query",
13
+ "operationId": "getShipmentStatusCounts",
14
+ "inputType": "GetShipmentStatusCountsInput",
15
+ "description": "Count registered parcels by delivery status without exposing tracking numbers or customer data.",
16
+ "fields": {
17
+ "stepType": "stepType",
18
+ "annotations": "annotations",
19
+ "connectionName": "connectionName",
20
+ "resultAttribute": "resultAttribute"
21
+ },
22
+ "branches": [
23
+ {
24
+ "id": "counted",
25
+ "field": "counted",
26
+ "optional": false
27
+ },
28
+ {
29
+ "id": "providerRejected",
30
+ "field": "providerRejected",
31
+ "optional": true
32
+ },
33
+ {
34
+ "id": "invalidResponse",
35
+ "field": "invalidResponse",
36
+ "optional": true
37
+ },
38
+ {
39
+ "id": "defect",
40
+ "field": "defect",
41
+ "optional": true
42
+ }
43
+ ],
44
+ "inputSchema": {
45
+ "additionalProperties": false,
46
+ "description": "GetShipmentStatusCountsInput selects the account's aggregate parcel statuses.",
47
+ "properties": {},
48
+ "type": "object"
49
+ }
50
+ }
51
+ ]
52
+ }
@@ -0,0 +1,121 @@
1
+ // src/generated/models.ts
2
+ import { z } from "zod";
3
+ import { SecretString } from "@superdurable/connectors-sdk";
4
+ var ConfigSchema = z.object({
5
+ "baseUrl": z.string().optional(),
6
+ "timeoutMs": z.number().int().optional(),
7
+ "maxResponseBytes": z.number().int().optional()
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(["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["api_key"] != null && !(typeof fields["api_key"] === "string")) throw new CredentialMaterialError("credential api_key has an invalid type");
29
+ const credentials = {};
30
+ if (!fields["api_key"]) throw new CredentialMaterialError("credential api_key is required");
31
+ credentials.apiKey = new SecretString(fields["api_key"] ?? "");
32
+ return credentials;
33
+ }
34
+ var GetShipmentStatusCountsInputSchema = z.strictObject({});
35
+ var ShipmentStatusCountsSchema = z.strictObject({
36
+ "pending": z.number().int(),
37
+ "notFound": z.number().int(),
38
+ "inTransit": z.number().int(),
39
+ "pickup": z.number().int(),
40
+ "delivered": z.number().int(),
41
+ "expired": z.number().int(),
42
+ "undelivered": z.number().int(),
43
+ "exception": z.number().int()
44
+ });
45
+
46
+ // src/generated/definitions.ts
47
+ var ConnectorID = "fiftyonetracking";
48
+ var ProviderID = "fiftyonetracking";
49
+ var GetShipmentStatusCountsBranch = {
50
+ Counted: "counted",
51
+ ProviderRejected: "providerRejected",
52
+ InvalidResponse: "invalidResponse",
53
+ Defect: "defect"
54
+ };
55
+ var GetShipmentStatusCountsBranchCounted = GetShipmentStatusCountsBranch.Counted;
56
+ var GetShipmentStatusCountsBranchProviderRejected = GetShipmentStatusCountsBranch.ProviderRejected;
57
+ var GetShipmentStatusCountsBranchInvalidResponse = GetShipmentStatusCountsBranch.InvalidResponse;
58
+ var GetShipmentStatusCountsBranchDefect = GetShipmentStatusCountsBranch.Defect;
59
+ var GetShipmentStatusCountsDefinition = {
60
+ operation: { connectorId: ConnectorID, operationId: "getShipmentStatusCounts" },
61
+ branches: [
62
+ { id: "counted", description: "51Tracking returned aggregate parcel status counts." },
63
+ { id: "providerRejected", description: "51Tracking rejected the key or request.", optional: true },
64
+ { id: "invalidResponse", description: "51Tracking returned malformed or oversized status data.", optional: true },
65
+ { id: "defect", description: "Local API key is invalid.", optional: true }
66
+ ],
67
+ stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "async" }
68
+ };
69
+ var GetShipmentStatusCountsMetadata = { kind: "query", idempotency: "none", authorization: "required" };
70
+
71
+ // src/generated/connection.ts
72
+ import { ConnectionRefSchema } from "@superdurable/connectors-sdk";
73
+ var Connection = class {
74
+ /** Stable provider and connection name. */
75
+ reference;
76
+ /** Bound provider operations. */
77
+ operations;
78
+ /** Validate a reference and bind operations. */
79
+ constructor(reference, operations) {
80
+ this.reference = ConnectionRefSchema.parse(reference);
81
+ if (this.reference.provider !== ProviderID) throw new TypeError("connection provider differs from the manifest");
82
+ if (!operations) throw new TypeError("connector operations are required");
83
+ this.operations = operations;
84
+ }
85
+ };
86
+ function newConnection(client, reference) {
87
+ if (!client) throw new TypeError("connector client is required");
88
+ return new Connection(reference, client);
89
+ }
90
+ function newConnectionWithOperations(operations, reference) {
91
+ return new Connection(reference, operations);
92
+ }
93
+ function newProjectConnection(project, connectionName, createClient) {
94
+ if (!project) throw new TypeError("loaded project is required");
95
+ const reference = ConnectionRefSchema.parse({ provider: ProviderID, name: connectionName });
96
+ const selected = project.configuration.connections.find((entry) => entry.connectorId === ConnectorID && entry.connectionName === connectionName);
97
+ if (!selected || selected.provider !== ProviderID) throw new TypeError("project connection is not configured");
98
+ return newConnection(createClient(project, connectionName), reference);
99
+ }
100
+
101
+ export {
102
+ ConfigSchema,
103
+ CredentialMaterialError,
104
+ isCredentialMaterialError,
105
+ decodeCredentials,
106
+ GetShipmentStatusCountsInputSchema,
107
+ ShipmentStatusCountsSchema,
108
+ ConnectorID,
109
+ ProviderID,
110
+ GetShipmentStatusCountsBranch,
111
+ GetShipmentStatusCountsBranchCounted,
112
+ GetShipmentStatusCountsBranchProviderRejected,
113
+ GetShipmentStatusCountsBranchInvalidResponse,
114
+ GetShipmentStatusCountsBranchDefect,
115
+ GetShipmentStatusCountsDefinition,
116
+ GetShipmentStatusCountsMetadata,
117
+ Connection,
118
+ newConnection,
119
+ newConnectionWithOperations,
120
+ newProjectConnection
121
+ };
@@ -0,0 +1,89 @@
1
+ import { CredentialProvider, SecretString, Query, ConnectionRef } from '@superdurable/connectors-sdk';
2
+ import { z } from 'zod';
3
+
4
+ /** Connector configuration; omitted fields use manifest defaults. */
5
+ interface Config {
6
+ /** HTTPS origin of the 51Tracking API. Leave blank for the displayed production endpoint; override only for a trusted test server or provider-approved proxy. */
7
+ baseUrl?: string;
8
+ /** Maximum duration of one status-count query as a positive Go duration such as 30s or 1m. Leave blank for the displayed default; raise it only when the provider responds slowly from your network. Runtime value in milliseconds. */
9
+ timeoutMs?: number;
10
+ /** Maximum status-count response size in bytes as a positive integer. Leave blank for the displayed default; raise only if the provider adds status fields. */
11
+ maxResponseBytes?: number;
12
+ }
13
+ /** Runtime schema for manifest configuration. */
14
+ declare const ConfigSchema: z.ZodObject<{
15
+ baseUrl: z.ZodOptional<z.ZodString>;
16
+ timeoutMs: z.ZodOptional<z.ZodNumber>;
17
+ maxResponseBytes: z.ZodOptional<z.ZodNumber>;
18
+ }, z.core.$strip>;
19
+ /** Private connector credentials resolved by the host. */
20
+ interface Credentials {
21
+ /** Secret API key from https://www.51tracking.com/ > sign in > Settings > Get API Key > name and generate. Copy the key without a prefix; blank prevents requests. Update this connection after rotation. */
22
+ apiKey: SecretString;
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;
32
+ /** Host-owned source of private connector credentials. */
33
+ type CredentialSource = CredentialProvider<Credentials>;
34
+ /** GetShipmentStatusCountsInput selects the account's aggregate parcel statuses. */
35
+ interface GetShipmentStatusCountsInput {
36
+ }
37
+ /** ShipmentStatusCounts contains aggregate registered-parcel counts without personal information. */
38
+ interface ShipmentStatusCounts {
39
+ /** Pending counts parcels awaiting the first lookup. */
40
+ "pending": number;
41
+ /** NotFound counts parcels without a carrier result. */
42
+ "notFound": number;
43
+ /** InTransit counts parcels in transit. */
44
+ "inTransit": number;
45
+ /** Pickup counts parcels ready for pickup. */
46
+ "pickup": number;
47
+ /** Delivered counts delivered parcels. */
48
+ "delivered": number;
49
+ /** Expired counts parcels that exceeded the tracking window. */
50
+ "expired": number;
51
+ /** Undelivered counts failed delivery attempts. */
52
+ "undelivered": number;
53
+ /** Exception counts parcels with exceptional delivery status. */
54
+ "exception": number;
55
+ }
56
+ /** Runtime validator for GetShipmentStatusCountsInput. */
57
+ declare const GetShipmentStatusCountsInputSchema: z.ZodObject<{}, z.core.$strict>;
58
+ /** Runtime validator for ShipmentStatusCounts. */
59
+ declare const ShipmentStatusCountsSchema: z.ZodObject<{
60
+ pending: z.ZodNumber;
61
+ notFound: z.ZodNumber;
62
+ inTransit: z.ZodNumber;
63
+ pickup: z.ZodNumber;
64
+ delivered: z.ZodNumber;
65
+ expired: z.ZodNumber;
66
+ undelivered: z.ZodNumber;
67
+ exception: z.ZodNumber;
68
+ }, z.core.$strict>;
69
+
70
+ /** Typed operations supplied by a client or mock. */
71
+ interface Operations {
72
+ /** Invoke getShipmentStatusCounts through this connection. */
73
+ getShipmentStatusCounts(): Query<GetShipmentStatusCountsInput, ShipmentStatusCounts>;
74
+ }
75
+ /** Named connector connection kept outside Flow state. */
76
+ declare class Connection<BoundOperations = Operations> {
77
+ /** Stable provider and connection name. */
78
+ readonly reference: ConnectionRef;
79
+ /** Bound provider operations. */
80
+ readonly operations: BoundOperations;
81
+ /** Validate a reference and bind operations. */
82
+ constructor(reference: ConnectionRef, operations: BoundOperations);
83
+ }
84
+ /** Bind a client to a named connection. */
85
+ declare function newConnection(client: Operations, reference: ConnectionRef): Connection;
86
+ /** Bind scripted operations to a named connection. */
87
+ declare function newConnectionWithOperations(operations: Operations, reference: ConnectionRef): Connection;
88
+
89
+ export { Connection as C, type GetShipmentStatusCountsInput as G, type Operations as O, type ShipmentStatusCounts as S, type Config as a, type Credentials as b, ConfigSchema as c, CredentialMaterialError as d, type CredentialSource as e, GetShipmentStatusCountsInputSchema as f, ShipmentStatusCountsSchema as g, decodeCredentials as h, isCredentialMaterialError as i, newConnectionWithOperations as j, newConnection as n };
@@ -0,0 +1,90 @@
1
+ import { G as GetShipmentStatusCountsInput, S as ShipmentStatusCounts, C as Connection, O as Operations, a as Config, b as Credentials } from './connection-A09u3GS-.js';
2
+ export { c as ConfigSchema, d as CredentialMaterialError, e as CredentialSource, f as GetShipmentStatusCountsInputSchema, g as ShipmentStatusCountsSchema, h as decodeCredentials, i as isCredentialMaterialError, n as newConnection, j as newConnectionWithOperations } from './connection-A09u3GS-.js';
3
+ import { QueryDefinition, QueryStepConfig, Query, QueryResult, QueryStep, CredentialProvider, Call, QueryAttempt } from '@superdurable/connectors-sdk';
4
+ import { StepTarget } from '@superdurable/dex';
5
+ import { LoadedProject } from '@superdurable/connectors-sdk/projectconfig';
6
+ import { ProviderRequest, ProviderResponse } from '@superdurable/connectors-sdk/providerhttp';
7
+ import 'zod';
8
+
9
+ /** Stable connector identity. */
10
+ declare const ConnectorID = "fiftyonetracking";
11
+ /** Provider identity for named connections. */
12
+ declare const ProviderID = "fiftyonetracking";
13
+ /** Branch IDs for getShipmentStatusCounts. */
14
+ declare const GetShipmentStatusCountsBranch: {
15
+ readonly Counted: "counted";
16
+ readonly ProviderRejected: "providerRejected";
17
+ readonly InvalidResponse: "invalidResponse";
18
+ readonly Defect: "defect";
19
+ };
20
+ /** 51Tracking returned aggregate parcel status counts. */
21
+ declare const GetShipmentStatusCountsBranchCounted: "counted";
22
+ /** 51Tracking rejected the key or request. */
23
+ declare const GetShipmentStatusCountsBranchProviderRejected: "providerRejected";
24
+ /** 51Tracking returned malformed or oversized status data. */
25
+ declare const GetShipmentStatusCountsBranchInvalidResponse: "invalidResponse";
26
+ /** Local API key is invalid. */
27
+ declare const GetShipmentStatusCountsBranchDefect: "defect";
28
+ /** Manifest definition for getShipmentStatusCounts. */
29
+ declare const GetShipmentStatusCountsDefinition: QueryDefinition;
30
+ /** Manifest metadata for getShipmentStatusCounts. */
31
+ declare const GetShipmentStatusCountsMetadata: {
32
+ readonly kind: "query";
33
+ readonly idempotency: "none";
34
+ readonly authorization: "required";
35
+ };
36
+
37
+ /** Configuration for the getShipmentStatusCounts connector Step. */
38
+ interface GetShipmentStatusCountsStepConfig<StepInput, OperationInput = GetShipmentStatusCountsInput, OperationOutput = ShipmentStatusCounts> extends Omit<QueryStepConfig<StepInput, OperationInput, OperationOutput>, 'operation' | 'connection' | 'branches'> {
39
+ /** Named connection supplying this operation. */
40
+ connection: Connection<{
41
+ getShipmentStatusCounts(): Query<OperationInput, OperationOutput>;
42
+ }>;
43
+ /** Name matching the bound connection. */
44
+ connectionName: string;
45
+ /** 51Tracking returned aggregate parcel status counts. */
46
+ counted: StepTarget<QueryResult<OperationOutput>>;
47
+ /** 51Tracking rejected the key or request. */
48
+ providerRejected?: StepTarget<QueryResult<OperationOutput>>;
49
+ /** 51Tracking returned malformed or oversized status data. */
50
+ invalidResponse?: StepTarget<QueryResult<OperationOutput>>;
51
+ /** Local API key is invalid. */
52
+ defect?: StepTarget<QueryResult<OperationOutput>>;
53
+ }
54
+ /** Build the getShipmentStatusCounts Step from a named connection. */
55
+ declare function newGetShipmentStatusCountsStep<StepInput, OperationInput = GetShipmentStatusCountsInput, OperationOutput = ShipmentStatusCounts>(configuration: GetShipmentStatusCountsStepConfig<StepInput, OperationInput, OperationOutput>): QueryStep<StepInput, OperationInput, OperationOutput>;
56
+
57
+ /** Open one named Fiftyonetracking connection from Dex project configuration. */
58
+ declare function newProjectConnection(project: LoadedProject, connectionName: string): Connection<Operations>;
59
+
60
+ /** Optional provider sender for local tests. */
61
+ interface FiftyonetrackingClientOptions {
62
+ /** Sender; omitted uses the SDK HTTP transport. */ send?: (request: ProviderRequest) => Promise<ProviderResponse>;
63
+ }
64
+ /** Read aggregate parcel statuses from 51Tracking. */
65
+ declare class FiftyonetrackingClient {
66
+ private readonly credentials;
67
+ private readonly baseUrl;
68
+ private readonly timeoutMs;
69
+ private readonly maxResponseBytes;
70
+ private readonly send;
71
+ /** Validate local limits without contacting 51Tracking. */
72
+ constructor(config: Config, credentials: CredentialProvider<Credentials>, options?: FiftyonetrackingClientOptions);
73
+ /** Bind the parcel-status Query. */ getShipmentStatusCounts(): GetShipmentStatusCountsOperation;
74
+ /** Send one bounded status-count request. */
75
+ list(call: Call): Promise<{
76
+ response?: ProviderResponse;
77
+ error?: 'credential' | 'transport' | 'tooLarge';
78
+ retryAfterMs: number;
79
+ }>;
80
+ }
81
+ /** Read the current 51Tracking parcel-status counts. */
82
+ declare class GetShipmentStatusCountsOperation implements Query<GetShipmentStatusCountsInput, ShipmentStatusCounts> {
83
+ private readonly client;
84
+ /** Bind the provider client. */ constructor(client: FiftyonetrackingClient);
85
+ /** Return the generated Query definition. */ definition(): QueryDefinition;
86
+ /** Classify one status-count request using the Go connector contract. */
87
+ invoke(call: Call): Promise<QueryAttempt<ShipmentStatusCounts>>;
88
+ }
89
+
90
+ export { Config, Connection, ConnectorID, Credentials, FiftyonetrackingClient, type FiftyonetrackingClientOptions, GetShipmentStatusCountsBranch, GetShipmentStatusCountsBranchCounted, GetShipmentStatusCountsBranchDefect, GetShipmentStatusCountsBranchInvalidResponse, GetShipmentStatusCountsBranchProviderRejected, GetShipmentStatusCountsDefinition, GetShipmentStatusCountsInput, GetShipmentStatusCountsMetadata, type GetShipmentStatusCountsStepConfig, ProviderID, ShipmentStatusCounts, newGetShipmentStatusCountsStep, newProjectConnection };
package/dist/index.js ADDED
@@ -0,0 +1,193 @@
1
+ import {
2
+ ConfigSchema,
3
+ Connection,
4
+ ConnectorID,
5
+ CredentialMaterialError,
6
+ GetShipmentStatusCountsBranch,
7
+ GetShipmentStatusCountsBranchCounted,
8
+ GetShipmentStatusCountsBranchDefect,
9
+ GetShipmentStatusCountsBranchInvalidResponse,
10
+ GetShipmentStatusCountsBranchProviderRejected,
11
+ GetShipmentStatusCountsDefinition,
12
+ GetShipmentStatusCountsInputSchema,
13
+ GetShipmentStatusCountsMetadata,
14
+ ProviderID,
15
+ ShipmentStatusCountsSchema,
16
+ decodeCredentials,
17
+ isCredentialMaterialError,
18
+ newConnection,
19
+ newConnectionWithOperations,
20
+ newProjectConnection
21
+ } from "./chunk-3CO2KYN4.js";
22
+
23
+ // src/generated/steps.ts
24
+ import { goToBranch, newQueryStep } from "@superdurable/connectors-sdk";
25
+ function newGetShipmentStatusCountsStep(configuration) {
26
+ const { connection, connectionName, counted, providerRejected, invalidResponse, defect, ...stepConfiguration } = configuration;
27
+ if (!connection || connection.reference.name !== connectionName) throw new TypeError("Step connection name differs from the bound connection");
28
+ return newQueryStep({ ...stepConfiguration, operation: connection.operations.getShipmentStatusCounts(), connection: connection.reference, branches: [
29
+ goToBranch("counted", counted),
30
+ ...providerRejected ? [goToBranch("providerRejected", providerRejected)] : [],
31
+ ...invalidResponse ? [goToBranch("invalidResponse", invalidResponse)] : [],
32
+ ...defect ? [goToBranch("defect", defect)] : []
33
+ ] });
34
+ }
35
+
36
+ // src/client.ts
37
+ import { SecretString, newQueryBranch, newQueryRetry } from "@superdurable/connectors-sdk";
38
+ import { BodyTooLargeError, parseRetryAfter, sendProviderRequest } from "@superdurable/connectors-sdk/providerhttp";
39
+ var statusPath = "/v3/trackings/status";
40
+ var emptyCounts = { pending: 0, notFound: 0, inTransit: 0, pickup: 0, delivered: 0, expired: 0, undelivered: 0, exception: 0 };
41
+ var FiftyonetrackingClient = class {
42
+ /** Validate local limits without contacting 51Tracking. */
43
+ constructor(config, credentials, options = {}) {
44
+ this.credentials = credentials;
45
+ if (!config || !credentials) throw new TypeError("51Tracking configuration and credentials are required");
46
+ this.timeoutMs = config.timeoutMs || 15e3;
47
+ this.maxResponseBytes = config.maxResponseBytes || 1048576;
48
+ if (!Number.isSafeInteger(this.timeoutMs) || this.timeoutMs <= 0 || !Number.isSafeInteger(this.maxResponseBytes) || this.maxResponseBytes <= 0 || this.maxResponseBytes > 16 << 20) throw new TypeError("51Tracking request limits are invalid");
49
+ let parsedUrl;
50
+ try {
51
+ parsedUrl = new URL(config.baseUrl || "https://api.51tracking.com");
52
+ } catch {
53
+ throw new TypeError("51Tracking baseUrl must be an HTTPS origin");
54
+ }
55
+ if (parsedUrl.protocol !== "https:" || !parsedUrl.hostname || parsedUrl.username || parsedUrl.password || parsedUrl.search || parsedUrl.hash || parsedUrl.pathname !== "/" && parsedUrl.pathname !== "" || parsedUrl.hostname === "localhost") throw new TypeError("51Tracking baseUrl must be an HTTPS origin");
56
+ this.baseUrl = parsedUrl.origin;
57
+ this.send = options.send ?? sendProviderRequest;
58
+ }
59
+ credentials;
60
+ baseUrl;
61
+ timeoutMs;
62
+ maxResponseBytes;
63
+ send;
64
+ /** Bind the parcel-status Query. */
65
+ getShipmentStatusCounts() {
66
+ return new GetShipmentStatusCountsOperation(this);
67
+ }
68
+ /** Send one bounded status-count request. */
69
+ async list(call) {
70
+ let apiKey = "";
71
+ try {
72
+ const credentials = await this.credentials.resolve(call, call.context.cancellationSignal);
73
+ apiKey = credentials.apiKey instanceof SecretString ? credentials.apiKey.reveal() : "";
74
+ } catch {
75
+ return { error: "credential", retryAfterMs: 0 };
76
+ }
77
+ if (!apiKey || apiKey.length > 2048 || /[^\x21-\x7e]/.test(apiKey)) return { error: "credential", retryAfterMs: 0 };
78
+ const request = { url: this.baseUrl + statusPath, method: "GET", headers: { Accept: "application/json", "Content-Type": "application/json", "Tracking-Api-Key": apiKey }, timeoutMs: this.timeoutMs, maxResponseBytes: this.maxResponseBytes, addressPolicy: "publicHTTPS", signal: call.context.cancellationSignal };
79
+ let response;
80
+ try {
81
+ response = await this.send(request);
82
+ } catch (error) {
83
+ if (error instanceof BodyTooLargeError && error.status !== void 0) return { response: { status: error.status, headers: error.headers ?? {}, body: new Uint8Array() }, error: "tooLarge", retryAfterMs: 0 };
84
+ return { error: "transport", retryAfterMs: 0 };
85
+ }
86
+ return { response, error: response.body.length > this.maxResponseBytes ? "tooLarge" : void 0, retryAfterMs: parseRetryAfter(header(response.headers, "retry-after")) };
87
+ }
88
+ };
89
+ var GetShipmentStatusCountsOperation = class {
90
+ /** Bind the provider client. */
91
+ constructor(client) {
92
+ this.client = client;
93
+ }
94
+ client;
95
+ /** Return the generated Query definition. */
96
+ definition() {
97
+ return GetShipmentStatusCountsDefinition;
98
+ }
99
+ /** Classify one status-count request using the Go connector contract. */
100
+ async invoke(call) {
101
+ const exchange = await this.client.list(call);
102
+ if (exchange.error === "credential") return branch("defect", "AUTHENTICATION");
103
+ if (exchange.error === "transport" || !exchange.response) return retry("AVAILABILITY");
104
+ const { status, body } = exchange.response;
105
+ if (status === 429) return retry("RATE_LIMIT", exchange.retryAfterMs);
106
+ if (status === 408 || status >= 500) return retry("AVAILABILITY", exchange.retryAfterMs);
107
+ if (exchange.error === "tooLarge") return branch("invalidResponse", "RESPONSE_TOO_LARGE");
108
+ if (status !== 200) return branch("providerRejected", status === 401 ? "AUTHENTICATION" : status === 403 ? "AUTHORIZATION" : [400, 404, 412].includes(status) ? "VALIDATION" : "PROVIDER_REJECTION");
109
+ let wire;
110
+ try {
111
+ wire = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
112
+ } catch {
113
+ wire = void 0;
114
+ }
115
+ if (!isObject(wire) || typeof wire.code !== "number" || !Number.isSafeInteger(wire.code)) return branch("invalidResponse", "PROTOCOL");
116
+ if (wire.code !== 200) return branch("providerRejected", "PROVIDER_REJECTION");
117
+ const data = wire.data;
118
+ if (!isObject(data)) return branch("invalidResponse", "PROTOCOL");
119
+ const fields = ["pending", "notfound", "transit", "pickup", "delivered", "expired", "undelivered", "exception"];
120
+ if (fields.some((field) => typeof data[field] !== "number" || !Number.isSafeInteger(data[field]) || data[field] < 0)) return branch("invalidResponse", "PROTOCOL");
121
+ return newQueryBranch("counted", { pending: data.pending, notFound: data.notfound, inTransit: data.transit, pickup: data.pickup, delivered: data.delivered, expired: data.expired, undelivered: data.undelivered, exception: data.exception });
122
+ }
123
+ };
124
+ function isObject(value) {
125
+ return typeof value === "object" && value !== null && !Array.isArray(value);
126
+ }
127
+ function header(headers, name) {
128
+ const value = Object.entries(headers).find(([key]) => key.toLowerCase() === name)?.[1];
129
+ return Array.isArray(value) ? value[0] ?? "" : value ?? "";
130
+ }
131
+ function failure(kind) {
132
+ return { provider: "fiftyonetracking", operation: "getShipmentStatusCounts", kind, message: "51Tracking status-count query failed" };
133
+ }
134
+ function branch(name, kind) {
135
+ return newQueryBranch(name, { ...emptyCounts }, {}, failure(kind));
136
+ }
137
+ function retry(kind, delay = 0) {
138
+ return newQueryRetry(failure(kind), delay);
139
+ }
140
+
141
+ // src/project.ts
142
+ function newProjectConnection2(project, connectionName) {
143
+ return newProjectConnection(project, connectionName, (loadedProject, name) => {
144
+ const selected = loadedProject.configuration.connections.find((entry) => entry.connectorId === "fiftyonetracking" && entry.connectionName === name);
145
+ if (!selected) throw new TypeError("Fiftyonetracking project connection is not configured");
146
+ const fields = selected.configuration;
147
+ const config = ConfigSchema.parse({ ...fields, ...fields.timeout !== void 0 ? { timeoutMs: parseDurationMilliseconds(fields.timeout) } : {} });
148
+ const credentials = {
149
+ async resolve(_call, signal) {
150
+ return decodeCredentials(await loadedProject.resolveCredential("fiftyonetracking", name, signal));
151
+ }
152
+ };
153
+ return new FiftyonetrackingClient(config, credentials);
154
+ });
155
+ }
156
+ function parseDurationMilliseconds(value) {
157
+ if (typeof value === "number") return Math.ceil(value / 1e6);
158
+ if (typeof value !== "string") throw new TypeError("timeout must be a duration");
159
+ let remaining = value;
160
+ let milliseconds = 0;
161
+ const units = { ns: 1e-6, us: 1e-3, "\xB5s": 1e-3, ms: 1, s: 1e3, m: 6e4, h: 36e5 };
162
+ while (remaining) {
163
+ const part = /^(\d+(?:\.\d+)?)(ns|us|µs|ms|s|m|h)/.exec(remaining);
164
+ if (!part) throw new TypeError("timeout must be a positive Go duration");
165
+ milliseconds += Number(part[1]) * (units[part[2] ?? ""] ?? NaN);
166
+ remaining = remaining.slice(part[0].length);
167
+ }
168
+ if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) throw new TypeError("timeout must resolve to positive whole milliseconds");
169
+ return milliseconds;
170
+ }
171
+ export {
172
+ ConfigSchema,
173
+ Connection,
174
+ ConnectorID,
175
+ CredentialMaterialError,
176
+ FiftyonetrackingClient,
177
+ GetShipmentStatusCountsBranch,
178
+ GetShipmentStatusCountsBranchCounted,
179
+ GetShipmentStatusCountsBranchDefect,
180
+ GetShipmentStatusCountsBranchInvalidResponse,
181
+ GetShipmentStatusCountsBranchProviderRejected,
182
+ GetShipmentStatusCountsDefinition,
183
+ GetShipmentStatusCountsInputSchema,
184
+ GetShipmentStatusCountsMetadata,
185
+ ProviderID,
186
+ ShipmentStatusCountsSchema,
187
+ decodeCredentials,
188
+ isCredentialMaterialError,
189
+ newConnection,
190
+ newConnectionWithOperations,
191
+ newGetShipmentStatusCountsStep,
192
+ newProjectConnection2 as newProjectConnection
193
+ };
package/dist/mock.d.ts ADDED
@@ -0,0 +1,33 @@
1
+ import { MockQuery, Case } from '@superdurable/connectors-sdk/connectormock';
2
+ import { Failure } from '@superdurable/connectors-sdk';
3
+ import { O as Operations, C as Connection, G as GetShipmentStatusCountsInput, S as ShipmentStatusCounts } from './connection-A09u3GS-.js';
4
+ import 'zod';
5
+
6
+ /** Go zero value for GetShipmentStatusCountsInput in scripted cases. */
7
+ declare const emptyGetShipmentStatusCountsInput: GetShipmentStatusCountsInput;
8
+ /** Go zero value for ShipmentStatusCounts in scripted cases. */
9
+ declare const emptyShipmentStatusCounts: ShipmentStatusCounts;
10
+ /** Script the counted branch. */
11
+ declare function getShipmentStatusCountsCounted(value: ShipmentStatusCounts, failure?: Failure): Case<ShipmentStatusCounts>;
12
+ /** Script the providerRejected branch. */
13
+ declare function getShipmentStatusCountsProviderRejected(value: ShipmentStatusCounts, failure?: Failure): Case<ShipmentStatusCounts>;
14
+ /** Script the invalidResponse branch. */
15
+ declare function getShipmentStatusCountsInvalidResponse(value: ShipmentStatusCounts, failure?: Failure): Case<ShipmentStatusCounts>;
16
+ /** Script the defect branch. */
17
+ declare function getShipmentStatusCountsDefect(value: ShipmentStatusCounts, failure?: Failure): Case<ShipmentStatusCounts>;
18
+ /** Script a safe retry of getShipmentStatusCounts. */
19
+ declare function getShipmentStatusCountsRetry(failure: Failure, retryAfterMs?: number): Case<ShipmentStatusCounts>;
20
+ /** Manifest scenario countedParcels for getShipmentStatusCounts. */
21
+ declare function getShipmentStatusCountsCountedParcels(): Case<ShipmentStatusCounts>;
22
+ /** Default getShipmentStatusCounts scenario. */
23
+ declare function getShipmentStatusCountsDefault(): Case<ShipmentStatusCounts>;
24
+ /** Scripted operations and manifest defaults for this connector. */
25
+ declare class GeneratedMock implements Operations {
26
+ #private;
27
+ constructor(connectionName: string);
28
+ connection(): Connection;
29
+ getShipmentStatusCounts(): MockQuery<GetShipmentStatusCountsInput, ShipmentStatusCounts>;
30
+ assertNoFailures(): void;
31
+ }
32
+
33
+ export { GeneratedMock, emptyGetShipmentStatusCountsInput, emptyShipmentStatusCounts, getShipmentStatusCountsCounted, getShipmentStatusCountsCountedParcels, getShipmentStatusCountsDefault, getShipmentStatusCountsDefect, getShipmentStatusCountsInvalidResponse, getShipmentStatusCountsProviderRejected, getShipmentStatusCountsRetry };
package/dist/mock.js ADDED
@@ -0,0 +1,72 @@
1
+ import {
2
+ GetShipmentStatusCountsDefinition,
3
+ GetShipmentStatusCountsInputSchema,
4
+ ProviderID,
5
+ ShipmentStatusCountsSchema,
6
+ newConnectionWithOperations
7
+ } from "./chunk-3CO2KYN4.js";
8
+
9
+ // src/generated/mock.ts
10
+ import { branchCase, retryCase, newQuery } from "@superdurable/connectors-sdk/connectormock";
11
+ var emptyGetShipmentStatusCountsInput = GetShipmentStatusCountsInputSchema.parse({});
12
+ var emptyShipmentStatusCounts = ShipmentStatusCountsSchema.parse({
13
+ "pending": 0,
14
+ "notFound": 0,
15
+ "inTransit": 0,
16
+ "pickup": 0,
17
+ "delivered": 0,
18
+ "expired": 0,
19
+ "undelivered": 0,
20
+ "exception": 0
21
+ });
22
+ function getShipmentStatusCountsCounted(value, failure) {
23
+ return branchCase("counted", value, failure);
24
+ }
25
+ function getShipmentStatusCountsProviderRejected(value, failure) {
26
+ return branchCase("providerRejected", value, failure);
27
+ }
28
+ function getShipmentStatusCountsInvalidResponse(value, failure) {
29
+ return branchCase("invalidResponse", value, failure);
30
+ }
31
+ function getShipmentStatusCountsDefect(value, failure) {
32
+ return branchCase("defect", value, failure);
33
+ }
34
+ function getShipmentStatusCountsRetry(failure, retryAfterMs = 0) {
35
+ return retryCase(failure, retryAfterMs);
36
+ }
37
+ function getShipmentStatusCountsCountedParcels() {
38
+ const value = ShipmentStatusCountsSchema.parse({ "delivered": 5, "exception": 0, "expired": 0, "inTransit": 3, "notFound": 2, "pending": 1, "pickup": 4, "undelivered": 0 });
39
+ return branchCase("counted", value);
40
+ }
41
+ function getShipmentStatusCountsDefault() {
42
+ return getShipmentStatusCountsCountedParcels();
43
+ }
44
+ var GeneratedMock = class {
45
+ #getShipmentStatusCounts;
46
+ #connection;
47
+ constructor(connectionName) {
48
+ this.#getShipmentStatusCounts = newQuery(GetShipmentStatusCountsDefinition).default(getShipmentStatusCountsDefault());
49
+ this.#connection = newConnectionWithOperations(this, { provider: ProviderID, name: connectionName });
50
+ }
51
+ connection() {
52
+ return this.#connection;
53
+ }
54
+ getShipmentStatusCounts() {
55
+ return this.#getShipmentStatusCounts;
56
+ }
57
+ assertNoFailures() {
58
+ this.#getShipmentStatusCounts.assertNoFailures();
59
+ }
60
+ };
61
+ export {
62
+ GeneratedMock,
63
+ emptyGetShipmentStatusCountsInput,
64
+ emptyShipmentStatusCounts,
65
+ getShipmentStatusCountsCounted,
66
+ getShipmentStatusCountsCountedParcels,
67
+ getShipmentStatusCountsDefault,
68
+ getShipmentStatusCountsDefect,
69
+ getShipmentStatusCountsInvalidResponse,
70
+ getShipmentStatusCountsProviderRejected,
71
+ getShipmentStatusCountsRetry
72
+ };
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "@superdurable/connector-fiftyonetracking",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "license": "MIT",
5
+ "description": "fiftyonetracking connector for Dex TypeScript applications",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/superdurable/dex-connectors-library.git",
9
+ "directory": "connectors/fiftyonetracking/typescript"
10
+ },
11
+ "type": "module",
12
+ "engines": {
13
+ "node": "^22.0.0 || ^24.0.0"
14
+ },
15
+ "module": "./dist/index.js",
16
+ "types": "./dist/index.d.ts",
17
+ "exports": {
18
+ ".": {
19
+ "types": "./dist/index.d.ts",
20
+ "import": "./dist/index.js"
21
+ },
22
+ "./mock": {
23
+ "types": "./dist/mock.d.ts",
24
+ "import": "./dist/mock.js"
25
+ },
26
+ "./dex-connector.json": "./dex-connector.json"
27
+ },
28
+ "files": [
29
+ "dist",
30
+ "README.md",
31
+ "LICENSE",
32
+ "dex-connector.json"
33
+ ],
34
+ "scripts": {
35
+ "prepack": "npm run build",
36
+ "build": "tsup src/index.ts src/mock.ts --format esm --dts --clean",
37
+ "typecheck": "tsc --noEmit",
38
+ "lint": "eslint src test examples",
39
+ "test": "vitest run --exclude test/integration/**",
40
+ "test:integration": "vitest run test/integration/*.integration.test.ts",
41
+ "example:worker": "tsx examples/basic/worker.ts",
42
+ "example:start": "tsx examples/basic/start.ts",
43
+ "check": "npm run typecheck && npm run lint && npm test && npm run build"
44
+ },
45
+ "dependencies": {
46
+ "@superdurable/connectors-sdk": "0.1.1",
47
+ "@superdurable/dex": ">=1.28.0",
48
+ "zod": "^4.1.0"
49
+ },
50
+ "devDependencies": {
51
+ "@eslint/js": "^9.0.0",
52
+ "@types/node": "^22.0.0",
53
+ "eslint": "^9.0.0",
54
+ "tsup": "^8.0.0",
55
+ "tsx": "^4.23.15",
56
+ "typescript": "^5.9.0",
57
+ "typescript-eslint": "^8.0.0",
58
+ "vitest": "^3.0.0",
59
+ "yaml": "^2.9.1"
60
+ }
61
+ }