@superdurable/connector-yikeapi 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,7 @@
1
- # Temporary Holding Version
1
+ # YikeAPI 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
+ `@superdurable/connector-yikeapi` implements the read-only `lookupIPLocation` Query. It accepts a public IPv4 address and returns coarse country, province, city, and district fields. An App ID and App Secret are resolved from Dex Connections and sent to YikeAPI over HTTPS; it never enters Flow state or results.
4
+
5
+ Obtain a key through the provider account and API guidance linked in the [connector authorization guide](../connector.yaml). Leave timeout and maxResponseBytes blank for manifest defaults. Temporary transport and HTTP 408/429/5xx responses retry; provider refusals, malformed responses, and invalid local input select optional failure branches.
6
+
7
+ `examples/basic/` is a runnable Dex Flow, Worker, and Client. `npm run check` replays Go-recorded provider scenarios. `npm run test:integration` against `dexcli dev -open=false` verifies retry and persistence. Live provider authorization remains unverified without a user-controlled connection.
@@ -0,0 +1,60 @@
1
+ {
2
+ "connectorId": "yikeapi",
3
+ "releaseTag": "connectors/yikeapi/go/v0.1.0",
4
+ "package": {
5
+ "ecosystem": "npm",
6
+ "name": "@superdurable/connector-yikeapi",
7
+ "version": "0.1.0"
8
+ },
9
+ "factories": [
10
+ {
11
+ "name": "newLookupIPLocationStep",
12
+ "kind": "query",
13
+ "operationId": "lookupIPLocation",
14
+ "inputType": "LookupIPLocationInput",
15
+ "description": "Read country, province, city, and district for one public IPv4 address.",
16
+ "fields": {
17
+ "stepType": "stepType",
18
+ "annotations": "annotations",
19
+ "connectionName": "connectionName",
20
+ "resultAttribute": "resultAttribute"
21
+ },
22
+ "branches": [
23
+ {
24
+ "id": "found",
25
+ "field": "found",
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": "LookupIPLocationInput identifies one public IPv4 address.",
47
+ "properties": {
48
+ "ipAddress": {
49
+ "description": "IPAddress is an IPv4 address, not a hostname or CIDR range.",
50
+ "type": "string"
51
+ }
52
+ },
53
+ "required": [
54
+ "ipAddress"
55
+ ],
56
+ "type": "object"
57
+ }
58
+ }
59
+ ]
60
+ }
@@ -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
+ "timeoutMs": z.number().int().optional(),
6
+ "maxResponseBytes": z.number().int().optional()
7
+ });
8
+ var CredentialMaterialError = class extends TypeError {
9
+ constructor(message) {
10
+ super(message);
11
+ this.name = "CredentialMaterialError";
12
+ }
13
+ };
14
+ var sdkCredentialDecodingFailureMessages = /* @__PURE__ */ new Set([
15
+ "project credential decoding failed",
16
+ "shared project credential decoding failed",
17
+ "project credential decoding failed: this connector version does not support shared credentials"
18
+ ]);
19
+ function isCredentialMaterialError(error) {
20
+ return error instanceof CredentialMaterialError || error instanceof TypeError && sdkCredentialDecodingFailureMessages.has(error.message);
21
+ }
22
+ function decodeCredentials(value) {
23
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new CredentialMaterialError("credential fields are invalid");
24
+ const fields = value;
25
+ const allowed = /* @__PURE__ */ new Set(["appID", "appSecret"]);
26
+ if (Object.keys(fields).some((key) => !allowed.has(key))) throw new CredentialMaterialError("stored credential does not match the connector credential fields");
27
+ if (fields["appID"] != null && !(typeof fields["appID"] === "string")) throw new CredentialMaterialError("credential appID has an invalid type");
28
+ if (fields["appSecret"] != null && !(typeof fields["appSecret"] === "string")) throw new CredentialMaterialError("credential appSecret has an invalid type");
29
+ const credentials = {};
30
+ if (!fields["appID"]) throw new CredentialMaterialError("credential appID is required");
31
+ credentials.appID = new SecretString(fields["appID"] ?? "");
32
+ if (!fields["appSecret"]) throw new CredentialMaterialError("credential appSecret is required");
33
+ credentials.appSecret = new SecretString(fields["appSecret"] ?? "");
34
+ return credentials;
35
+ }
36
+ var LookupIPLocationInputSchema = z.strictObject({
37
+ "ipAddress": z.string()
38
+ });
39
+ var LookupIPLocationOutputSchema = z.strictObject({
40
+ "country": z.string(),
41
+ "province": z.string(),
42
+ "city": z.string(),
43
+ "district": z.string()
44
+ });
45
+
46
+ // src/generated/definitions.ts
47
+ var ConnectorID = "yikeapi";
48
+ var ProviderID = "yikeapi";
49
+ var LookupIPLocationBranch = {
50
+ Found: "found",
51
+ ProviderRejected: "providerRejected",
52
+ InvalidResponse: "invalidResponse",
53
+ Defect: "defect"
54
+ };
55
+ var LookupIPLocationBranchFound = LookupIPLocationBranch.Found;
56
+ var LookupIPLocationBranchProviderRejected = LookupIPLocationBranch.ProviderRejected;
57
+ var LookupIPLocationBranchInvalidResponse = LookupIPLocationBranch.InvalidResponse;
58
+ var LookupIPLocationBranchDefect = LookupIPLocationBranch.Defect;
59
+ var LookupIPLocationDefinition = {
60
+ operation: { connectorId: ConnectorID, operationId: "lookupIPLocation" },
61
+ branches: [
62
+ { id: "found", description: "YikeAPI returned the IP location." },
63
+ { id: "providerRejected", description: "YikeAPI rejected credentials, quota, or the query.", optional: true },
64
+ { id: "invalidResponse", description: "YikeAPI returned malformed or oversized data.", optional: true },
65
+ { id: "defect", description: "The local credentials or IP address are invalid.", optional: true }
66
+ ],
67
+ stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "async", executeRetry: { initialIntervalMs: 2e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 3, totalDurationMs: 3e5 } }
68
+ };
69
+ var LookupIPLocationMetadata = { 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
+ LookupIPLocationInputSchema,
107
+ LookupIPLocationOutputSchema,
108
+ ConnectorID,
109
+ ProviderID,
110
+ LookupIPLocationBranch,
111
+ LookupIPLocationBranchFound,
112
+ LookupIPLocationBranchProviderRejected,
113
+ LookupIPLocationBranchInvalidResponse,
114
+ LookupIPLocationBranchDefect,
115
+ LookupIPLocationDefinition,
116
+ LookupIPLocationMetadata,
117
+ Connection,
118
+ newConnection,
119
+ newConnectionWithOperations,
120
+ newProjectConnection
121
+ };
@@ -0,0 +1,80 @@
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
+ /** Maximum duration of one HTTPS IP lookup as a positive Go duration such as 5s or 1m. Blank uses the displayed default; increase only for a slow approved network. Runtime value in milliseconds. */
7
+ timeoutMs?: number;
8
+ /** Maximum provider response size in bytes as a positive integer. Blank uses the displayed default; increase only if a valid IP lookup response grows beyond it. */
9
+ maxResponseBytes?: number;
10
+ }
11
+ /** Runtime schema for manifest configuration. */
12
+ declare const ConfigSchema: z.ZodObject<{
13
+ timeoutMs: z.ZodOptional<z.ZodNumber>;
14
+ maxResponseBytes: z.ZodOptional<z.ZodNumber>;
15
+ }, z.core.$strip>;
16
+ /** Private connector credentials resolved by the host. */
17
+ interface Credentials {
18
+ /** Secret appid from https://www.yikeapi.com > 用户中心 after registering a developer account; copy it exactly. The provider requires it in the HTTPS query. Blank prevents requests. */
19
+ appID: SecretString;
20
+ /** Secret appsecret paired with appid in https://www.yikeapi.com > 用户中心; copy it exactly. The provider requires it in the HTTPS query. Blank prevents requests. */
21
+ appSecret: SecretString;
22
+ }
23
+ /** Stored credential material that fails the connector credential checks, so no retry can succeed. */
24
+ declare class CredentialMaterialError extends TypeError {
25
+ constructor(message: string);
26
+ }
27
+ /** Report malformed stored credential material, also behind the SDK provider's decoding TypeError. */
28
+ declare function isCredentialMaterialError(error: unknown): boolean;
29
+ /** Decode private credential fields for the connector. */
30
+ declare function decodeCredentials(value: unknown): Credentials;
31
+ /** Host-owned source of private connector credentials. */
32
+ type CredentialSource = CredentialProvider<Credentials>;
33
+ /** LookupIPLocationInput identifies one public IPv4 address. */
34
+ interface LookupIPLocationInput {
35
+ /** IPAddress is an IPv4 address, not a hostname or CIDR range. */
36
+ "ipAddress": string;
37
+ }
38
+ /** LookupIPLocationOutput contains only coarse location and network fields. */
39
+ interface LookupIPLocationOutput {
40
+ /** Country is the country name when returned by YIKEAPI. */
41
+ "country": string;
42
+ /** Province is the province name. */
43
+ "province": string;
44
+ /** City is the city name. */
45
+ "city": string;
46
+ /** District is the district name. */
47
+ "district": string;
48
+ }
49
+ /** Runtime validator for LookupIPLocationInput. */
50
+ declare const LookupIPLocationInputSchema: z.ZodObject<{
51
+ ipAddress: z.ZodString;
52
+ }, z.core.$strict>;
53
+ /** Runtime validator for LookupIPLocationOutput. */
54
+ declare const LookupIPLocationOutputSchema: z.ZodObject<{
55
+ country: z.ZodString;
56
+ province: z.ZodString;
57
+ city: z.ZodString;
58
+ district: z.ZodString;
59
+ }, z.core.$strict>;
60
+
61
+ /** Typed operations supplied by a client or mock. */
62
+ interface Operations {
63
+ /** Invoke lookupIPLocation through this connection. */
64
+ lookupIPLocation(): Query<LookupIPLocationInput, LookupIPLocationOutput>;
65
+ }
66
+ /** Named connector connection kept outside Flow state. */
67
+ declare class Connection<BoundOperations = Operations> {
68
+ /** Stable provider and connection name. */
69
+ readonly reference: ConnectionRef;
70
+ /** Bound provider operations. */
71
+ readonly operations: BoundOperations;
72
+ /** Validate a reference and bind operations. */
73
+ constructor(reference: ConnectionRef, operations: BoundOperations);
74
+ }
75
+ /** Bind a client to a named connection. */
76
+ declare function newConnection(client: Operations, reference: ConnectionRef): Connection;
77
+ /** Bind scripted operations to a named connection. */
78
+ declare function newConnectionWithOperations(operations: Operations, reference: ConnectionRef): Connection;
79
+
80
+ export { Connection as C, type LookupIPLocationInput as L, type Operations as O, type LookupIPLocationOutput as a, type Credentials as b, type Config as c, ConfigSchema as d, CredentialMaterialError as e, type CredentialSource as f, LookupIPLocationInputSchema as g, LookupIPLocationOutputSchema as h, decodeCredentials as i, isCredentialMaterialError as j, newConnectionWithOperations as k, newConnection as n };
@@ -0,0 +1,84 @@
1
+ import { L as LookupIPLocationInput, a as LookupIPLocationOutput, C as Connection, O as Operations, b as Credentials, c as Config } from './connection-Df7TO-tO.js';
2
+ export { d as ConfigSchema, e as CredentialMaterialError, f as CredentialSource, g as LookupIPLocationInputSchema, h as LookupIPLocationOutputSchema, i as decodeCredentials, j as isCredentialMaterialError, n as newConnection, k as newConnectionWithOperations } from './connection-Df7TO-tO.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 = "yikeapi";
11
+ /** Provider identity for named connections. */
12
+ declare const ProviderID = "yikeapi";
13
+ /** Branch IDs for lookupIPLocation. */
14
+ declare const LookupIPLocationBranch: {
15
+ readonly Found: "found";
16
+ readonly ProviderRejected: "providerRejected";
17
+ readonly InvalidResponse: "invalidResponse";
18
+ readonly Defect: "defect";
19
+ };
20
+ /** YikeAPI returned the IP location. */
21
+ declare const LookupIPLocationBranchFound: "found";
22
+ /** YikeAPI rejected credentials, quota, or the query. */
23
+ declare const LookupIPLocationBranchProviderRejected: "providerRejected";
24
+ /** YikeAPI returned malformed or oversized data. */
25
+ declare const LookupIPLocationBranchInvalidResponse: "invalidResponse";
26
+ /** The local credentials or IP address are invalid. */
27
+ declare const LookupIPLocationBranchDefect: "defect";
28
+ /** Manifest definition for lookupIPLocation. */
29
+ declare const LookupIPLocationDefinition: QueryDefinition;
30
+ /** Manifest metadata for lookupIPLocation. */
31
+ declare const LookupIPLocationMetadata: {
32
+ readonly kind: "query";
33
+ readonly idempotency: "none";
34
+ readonly authorization: "required";
35
+ };
36
+
37
+ /** Configuration for the lookupIPLocation connector Step. */
38
+ interface LookupIPLocationStepConfig<StepInput, OperationInput = LookupIPLocationInput, OperationOutput = LookupIPLocationOutput> extends Omit<QueryStepConfig<StepInput, OperationInput, OperationOutput>, 'operation' | 'connection' | 'branches'> {
39
+ /** Named connection supplying this operation. */
40
+ connection: Connection<{
41
+ lookupIPLocation(): Query<OperationInput, OperationOutput>;
42
+ }>;
43
+ /** Name matching the bound connection. */
44
+ connectionName: string;
45
+ /** YikeAPI returned the IP location. */
46
+ found: StepTarget<QueryResult<OperationOutput>>;
47
+ /** YikeAPI rejected credentials, quota, or the query. */
48
+ providerRejected?: StepTarget<QueryResult<OperationOutput>>;
49
+ /** YikeAPI returned malformed or oversized data. */
50
+ invalidResponse?: StepTarget<QueryResult<OperationOutput>>;
51
+ /** The local credentials or IP address are invalid. */
52
+ defect?: StepTarget<QueryResult<OperationOutput>>;
53
+ }
54
+ /** Build the lookupIPLocation Step from a named connection. */
55
+ declare function newLookupIPLocationStep<StepInput, OperationInput = LookupIPLocationInput, OperationOutput = LookupIPLocationOutput>(configuration: LookupIPLocationStepConfig<StepInput, OperationInput, OperationOutput>): QueryStep<StepInput, OperationInput, OperationOutput>;
56
+
57
+ /** Open one named YikeAPI connection from Dex project configuration. */
58
+ declare function newProjectConnection(project: LoadedProject, connectionName: string): Connection<Operations>;
59
+
60
+ /** Optional provider sender for deterministic tests. */
61
+ interface YikeAPIClientOptions {
62
+ send?: (request: ProviderRequest) => Promise<ProviderResponse>;
63
+ }
64
+ /** Resolve credentials for each read-only IP location Query. */
65
+ declare class YikeAPIClient {
66
+ readonly credentials: CredentialProvider<Credentials>;
67
+ readonly timeoutMs: number;
68
+ readonly maxResponseBytes: number;
69
+ readonly send: (request: ProviderRequest) => Promise<ProviderResponse>;
70
+ /** Validate request limits without contacting the provider. */
71
+ constructor(config: Config, credentials: CredentialProvider<Credentials>, options?: YikeAPIClientOptions);
72
+ /** Bind the IP location Query. */
73
+ lookupIPLocation(): LookupIPLocationOperation;
74
+ }
75
+ /** Read coarse location fields for a public IPv4 address. */
76
+ declare class LookupIPLocationOperation implements Query<LookupIPLocationInput, LookupIPLocationOutput> {
77
+ private readonly client;
78
+ /** Bind a validated provider client. */ constructor(client: YikeAPIClient);
79
+ /** Return the generated Query contract. */ definition(): QueryDefinition;
80
+ /** Classify a provider attempt without exposing credentials. */
81
+ invoke(call: Call, input: LookupIPLocationInput): Promise<QueryAttempt<LookupIPLocationOutput>>;
82
+ }
83
+
84
+ export { Config, Connection, ConnectorID, Credentials, LookupIPLocationBranch, LookupIPLocationBranchDefect, LookupIPLocationBranchFound, LookupIPLocationBranchInvalidResponse, LookupIPLocationBranchProviderRejected, LookupIPLocationDefinition, LookupIPLocationInput, LookupIPLocationMetadata, LookupIPLocationOutput, type LookupIPLocationStepConfig, ProviderID, YikeAPIClient, type YikeAPIClientOptions, newLookupIPLocationStep, newProjectConnection };
package/dist/index.js ADDED
@@ -0,0 +1,190 @@
1
+ import {
2
+ ConfigSchema,
3
+ Connection,
4
+ ConnectorID,
5
+ CredentialMaterialError,
6
+ LookupIPLocationBranch,
7
+ LookupIPLocationBranchDefect,
8
+ LookupIPLocationBranchFound,
9
+ LookupIPLocationBranchInvalidResponse,
10
+ LookupIPLocationBranchProviderRejected,
11
+ LookupIPLocationDefinition,
12
+ LookupIPLocationInputSchema,
13
+ LookupIPLocationMetadata,
14
+ LookupIPLocationOutputSchema,
15
+ ProviderID,
16
+ decodeCredentials,
17
+ isCredentialMaterialError,
18
+ newConnection,
19
+ newConnectionWithOperations,
20
+ newProjectConnection
21
+ } from "./chunk-HWCVAIXT.js";
22
+
23
+ // src/generated/steps.ts
24
+ import { goToBranch, newQueryStep } from "@superdurable/connectors-sdk";
25
+ function newLookupIPLocationStep(configuration) {
26
+ const { connection, connectionName, found, 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.lookupIPLocation(), connection: connection.reference, branches: [
29
+ goToBranch("found", found),
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 endpoint = "https://apia.yikeapi.com/ip/";
40
+ var emptyOutput = { country: "", province: "", city: "", district: "" };
41
+ var YikeAPIClient = class {
42
+ /** Validate request limits without contacting the provider. */
43
+ constructor(config, credentials, options = {}) {
44
+ this.credentials = credentials;
45
+ if (!config || !credentials) throw new TypeError("YikeAPI configuration and credentials are required");
46
+ this.timeoutMs = config.timeoutMs ?? 1e4;
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("YikeAPI request limits are invalid");
49
+ this.send = options.send ?? sendProviderRequest;
50
+ }
51
+ credentials;
52
+ timeoutMs;
53
+ maxResponseBytes;
54
+ send;
55
+ /** Bind the IP location Query. */
56
+ lookupIPLocation() {
57
+ return new LookupIPLocationOperation(this);
58
+ }
59
+ };
60
+ var LookupIPLocationOperation = class {
61
+ /** Bind a validated provider client. */
62
+ constructor(client) {
63
+ this.client = client;
64
+ }
65
+ client;
66
+ /** Return the generated Query contract. */
67
+ definition() {
68
+ return LookupIPLocationDefinition;
69
+ }
70
+ /** Classify a provider attempt without exposing credentials. */
71
+ async invoke(call, input) {
72
+ if (!input || !isPublicIPv4(input.ipAddress)) return branch("defect", "VALIDATION");
73
+ let appID = "";
74
+ let appSecret = "";
75
+ try {
76
+ const fields = await this.client.credentials.resolve(call, call.context.cancellationSignal);
77
+ appID = fields.appID instanceof SecretString ? fields.appID.reveal() : "";
78
+ appSecret = fields.appSecret instanceof SecretString ? fields.appSecret.reveal() : "";
79
+ } catch {
80
+ return branch("defect", "AUTHENTICATION");
81
+ }
82
+ if (!isValidCredential(appID) || !isValidCredential(appSecret)) return branch("defect", "AUTHENTICATION");
83
+ const url = new URL(endpoint);
84
+ url.searchParams.set("appid", appID);
85
+ url.searchParams.set("appsecret", appSecret);
86
+ url.searchParams.set("ip", input.ipAddress);
87
+ let response;
88
+ let tooLarge = false;
89
+ try {
90
+ response = await this.client.send({ url: url.toString(), method: "GET", headers: { Accept: "application/json" }, timeoutMs: this.client.timeoutMs, maxResponseBytes: this.client.maxResponseBytes, addressPolicy: "publicHTTPS", signal: call.context.cancellationSignal });
91
+ } catch (error) {
92
+ if (!(error instanceof BodyTooLargeError) || error.status === void 0) return retry("AVAILABILITY");
93
+ response = { status: error.status, headers: error.headers ?? {}, body: new Uint8Array() };
94
+ tooLarge = true;
95
+ }
96
+ const retryAfterValue = Object.entries(response.headers).find(([key]) => key.toLowerCase() === "retry-after")?.[1];
97
+ const retryAfterMs = parseRetryAfter(Array.isArray(retryAfterValue) ? retryAfterValue[0] ?? "" : retryAfterValue ?? "");
98
+ if (response.status === 429) return retry("RATE_LIMIT", retryAfterMs);
99
+ if (response.status === 408 || response.status >= 500) return retry("AVAILABILITY", retryAfterMs);
100
+ if (response.status !== 200) return branch("providerRejected", response.status === 401 ? "AUTHENTICATION" : response.status === 403 ? "AUTHORIZATION" : "PROVIDER_REJECTION");
101
+ if (tooLarge || response.body.length > this.client.maxResponseBytes) return branch("invalidResponse", "RESPONSE_TOO_LARGE");
102
+ let document;
103
+ try {
104
+ document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(response.body));
105
+ } catch {
106
+ return branch("invalidResponse", "PROTOCOL");
107
+ }
108
+ if (!isRecord(document) || !Number.isInteger(document.errcode)) return branch("invalidResponse", "PROTOCOL");
109
+ if (document.errcode !== 0) return branch("providerRejected", "PROVIDER_REJECTION");
110
+ if (document.ip !== input.ipAddress || typeof document.country !== "string" || !document.country.trim() || typeof document.province !== "string" || typeof document.city !== "string" || !document.city.trim() || typeof document.district !== "string") return branch("invalidResponse", "PROTOCOL");
111
+ return newQueryBranch("found", { country: document.country, province: document.province, city: document.city, district: document.district });
112
+ }
113
+ };
114
+ function isPublicIPv4(value) {
115
+ if (typeof value !== "string") return false;
116
+ const parts = value.split(".");
117
+ if (parts.length !== 4 || parts.some((part) => !/^(0|[1-9]\d{0,2})$/.test(part) || Number(part) > 255)) return false;
118
+ const first = Number(parts[0]);
119
+ const second = Number(parts[1]);
120
+ return first !== 0 && first !== 10 && first !== 127 && first < 224 && !(first === 169 && second === 254) && !(first === 172 && second >= 16 && second <= 31) && !(first === 192 && second === 168);
121
+ }
122
+ function isRecord(value) {
123
+ return typeof value === "object" && value !== null && !Array.isArray(value);
124
+ }
125
+ function isValidCredential(value) {
126
+ return value.length > 0 && value.length <= 512 && /^[!-~]+$/.test(value);
127
+ }
128
+ function failure(kind) {
129
+ return { provider: "yikeapi", operation: "lookupIPLocation", kind, message: "YikeAPI location lookup failed" };
130
+ }
131
+ function branch(name, kind) {
132
+ return newQueryBranch(name, emptyOutput, {}, failure(kind));
133
+ }
134
+ function retry(kind, delay = 0) {
135
+ return newQueryRetry(failure(kind), delay);
136
+ }
137
+
138
+ // src/project.ts
139
+ function newProjectConnection2(project, connectionName) {
140
+ return newProjectConnection(project, connectionName, (loadedProject, name) => {
141
+ const selected = loadedProject.configuration.connections.find((entry) => entry.connectorId === "yikeapi" && entry.connectionName === name);
142
+ if (!selected) throw new TypeError("YikeAPI project connection is not configured");
143
+ const fields = selected.configuration;
144
+ const config = ConfigSchema.parse({ ...fields, ...fields.timeout !== void 0 ? { timeoutMs: parseDurationMilliseconds(fields.timeout) } : {} });
145
+ const credentials = {
146
+ async resolve(_call, signal) {
147
+ return decodeCredentials(await loadedProject.resolveCredential("yikeapi", name, signal));
148
+ }
149
+ };
150
+ return new YikeAPIClient(config, credentials);
151
+ });
152
+ }
153
+ function parseDurationMilliseconds(value) {
154
+ if (typeof value === "number") return Math.ceil(value / 1e6);
155
+ if (typeof value !== "string") throw new TypeError("timeout must be a duration");
156
+ let remaining = value;
157
+ let milliseconds = 0;
158
+ const units = { ns: 1e-6, us: 1e-3, "\xB5s": 1e-3, ms: 1, s: 1e3, m: 6e4, h: 36e5 };
159
+ while (remaining) {
160
+ const part = /^(\d+(?:\.\d+)?)(ns|us|µs|ms|s|m|h)/.exec(remaining);
161
+ if (!part) throw new TypeError("timeout must be a positive Go duration");
162
+ milliseconds += Number(part[1]) * (units[part[2] ?? ""] ?? NaN);
163
+ remaining = remaining.slice(part[0].length);
164
+ }
165
+ if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) throw new TypeError("timeout must resolve to positive whole milliseconds");
166
+ return milliseconds;
167
+ }
168
+ export {
169
+ ConfigSchema,
170
+ Connection,
171
+ ConnectorID,
172
+ CredentialMaterialError,
173
+ LookupIPLocationBranch,
174
+ LookupIPLocationBranchDefect,
175
+ LookupIPLocationBranchFound,
176
+ LookupIPLocationBranchInvalidResponse,
177
+ LookupIPLocationBranchProviderRejected,
178
+ LookupIPLocationDefinition,
179
+ LookupIPLocationInputSchema,
180
+ LookupIPLocationMetadata,
181
+ LookupIPLocationOutputSchema,
182
+ ProviderID,
183
+ YikeAPIClient,
184
+ decodeCredentials,
185
+ isCredentialMaterialError,
186
+ newConnection,
187
+ newConnectionWithOperations,
188
+ newLookupIPLocationStep,
189
+ newProjectConnection2 as newProjectConnection
190
+ };
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, L as LookupIPLocationInput, a as LookupIPLocationOutput } from './connection-Df7TO-tO.js';
4
+ import 'zod';
5
+
6
+ /** Go zero value for LookupIPLocationInput in scripted cases. */
7
+ declare const emptyLookupIPLocationInput: LookupIPLocationInput;
8
+ /** Go zero value for LookupIPLocationOutput in scripted cases. */
9
+ declare const emptyLookupIPLocationOutput: LookupIPLocationOutput;
10
+ /** Script the found branch. */
11
+ declare function lookupIPLocationFound(value: LookupIPLocationOutput, failure?: Failure): Case<LookupIPLocationOutput>;
12
+ /** Script the providerRejected branch. */
13
+ declare function lookupIPLocationProviderRejected(value: LookupIPLocationOutput, failure?: Failure): Case<LookupIPLocationOutput>;
14
+ /** Script the invalidResponse branch. */
15
+ declare function lookupIPLocationInvalidResponse(value: LookupIPLocationOutput, failure?: Failure): Case<LookupIPLocationOutput>;
16
+ /** Script the defect branch. */
17
+ declare function lookupIPLocationDefect(value: LookupIPLocationOutput, failure?: Failure): Case<LookupIPLocationOutput>;
18
+ /** Script a safe retry of lookupIPLocation. */
19
+ declare function lookupIPLocationRetry(failure: Failure, retryAfterMs?: number): Case<LookupIPLocationOutput>;
20
+ /** Manifest scenario shenzhen for lookupIPLocation. */
21
+ declare function lookupIPLocationShenzhen(): Case<LookupIPLocationOutput>;
22
+ /** Default lookupIPLocation scenario. */
23
+ declare function lookupIPLocationDefault(): Case<LookupIPLocationOutput>;
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
+ lookupIPLocation(): MockQuery<LookupIPLocationInput, LookupIPLocationOutput>;
30
+ assertNoFailures(): void;
31
+ }
32
+
33
+ export { GeneratedMock, emptyLookupIPLocationInput, emptyLookupIPLocationOutput, lookupIPLocationDefault, lookupIPLocationDefect, lookupIPLocationFound, lookupIPLocationInvalidResponse, lookupIPLocationProviderRejected, lookupIPLocationRetry, lookupIPLocationShenzhen };
package/dist/mock.js ADDED
@@ -0,0 +1,70 @@
1
+ import {
2
+ LookupIPLocationDefinition,
3
+ LookupIPLocationInputSchema,
4
+ LookupIPLocationOutputSchema,
5
+ ProviderID,
6
+ newConnectionWithOperations
7
+ } from "./chunk-HWCVAIXT.js";
8
+
9
+ // src/generated/mock.ts
10
+ import { branchCase, retryCase, newQuery } from "@superdurable/connectors-sdk/connectormock";
11
+ var emptyLookupIPLocationInput = LookupIPLocationInputSchema.parse({
12
+ "ipAddress": ""
13
+ });
14
+ var emptyLookupIPLocationOutput = LookupIPLocationOutputSchema.parse({
15
+ "country": "",
16
+ "province": "",
17
+ "city": "",
18
+ "district": ""
19
+ });
20
+ function lookupIPLocationFound(value, failure) {
21
+ return branchCase("found", value, failure);
22
+ }
23
+ function lookupIPLocationProviderRejected(value, failure) {
24
+ return branchCase("providerRejected", value, failure);
25
+ }
26
+ function lookupIPLocationInvalidResponse(value, failure) {
27
+ return branchCase("invalidResponse", value, failure);
28
+ }
29
+ function lookupIPLocationDefect(value, failure) {
30
+ return branchCase("defect", value, failure);
31
+ }
32
+ function lookupIPLocationRetry(failure, retryAfterMs = 0) {
33
+ return retryCase(failure, retryAfterMs);
34
+ }
35
+ function lookupIPLocationShenzhen() {
36
+ const value = LookupIPLocationOutputSchema.parse({ "city": "\u6DF1\u5733\u5E02", "country": "\u4E2D\u56FD", "district": "\u9F99\u5C97\u533A", "province": "\u5E7F\u4E1C\u7701" });
37
+ return branchCase("found", value);
38
+ }
39
+ function lookupIPLocationDefault() {
40
+ return lookupIPLocationShenzhen();
41
+ }
42
+ var GeneratedMock = class {
43
+ #lookupIPLocation;
44
+ #connection;
45
+ constructor(connectionName) {
46
+ this.#lookupIPLocation = newQuery(LookupIPLocationDefinition).default(lookupIPLocationDefault());
47
+ this.#connection = newConnectionWithOperations(this, { provider: ProviderID, name: connectionName });
48
+ }
49
+ connection() {
50
+ return this.#connection;
51
+ }
52
+ lookupIPLocation() {
53
+ return this.#lookupIPLocation;
54
+ }
55
+ assertNoFailures() {
56
+ this.#lookupIPLocation.assertNoFailures();
57
+ }
58
+ };
59
+ export {
60
+ GeneratedMock,
61
+ emptyLookupIPLocationInput,
62
+ emptyLookupIPLocationOutput,
63
+ lookupIPLocationDefault,
64
+ lookupIPLocationDefect,
65
+ lookupIPLocationFound,
66
+ lookupIPLocationInvalidResponse,
67
+ lookupIPLocationProviderRejected,
68
+ lookupIPLocationRetry,
69
+ lookupIPLocationShenzhen
70
+ };
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "@superdurable/connector-yikeapi",
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": "YikeAPI IP-location connector for Dex TypeScript applications",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/superdurable/dex-connectors-library.git",
9
+ "directory": "connectors/yikeapi/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
+ }