@ghostgate/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,277 @@
+import { randomUUID } from "node:crypto";
+import { privateKeyToAccount } from "viem/accounts";
+import { GhostFulfillmentMerchant } from "./fulfillment.js";
+export * from "./fulfillment.js";
+const DEFAULT_BASE_URL = "https://ghostprotocol.cc";
+const DEFAULT_CHAIN_ID = 8453;
+const DEFAULT_SERVICE_SLUG = "connect";
+const DEFAULT_CREDIT_COST = 1;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+const ACCESS_TYPES = {
+    Access: [
+        { name: "service", type: "string" },
+        { name: "timestamp", type: "uint256" },
+        { name: "nonce", type: "string" },
+    ],
+};
+const normalizeBaseUrl = (value) => value.replace(/\/+$/, "");
+const normalizeOptionalString = (value) => {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+};
+const getApiKeyPrefix = (apiKey) => {
+    if (apiKey.length <= 8)
+        return apiKey;
+    return `${apiKey.slice(0, 8)}...`;
+};
+const parsePayload = async (response) => {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+};
+const deriveAgentId = (serviceSlug) => {
+    if (!serviceSlug)
+        return null;
+    const match = /^agent-(.+)$/i.exec(serviceSlug);
+    return match?.[1] ?? null;
+};
+const toOptionalMetadata = (value) => value && Object.keys(value).length > 0 ? value : undefined;
+const assertTelemetryIdentity = (input) => {
+    if (input.apiKey || input.agentId || input.serviceSlug)
+        return;
+    throw new Error("Telemetry calls require at least one of apiKey, agentId, or serviceSlug.");
+};
+const normalizeTelemetryStatusCode = (value) => {
+    if (value == null)
+        return null;
+    if (!Number.isInteger(value) || value < 100 || value > 599) {
+        throw new Error("statusCode must be an integer in the HTTP status range.");
+    }
+    return value;
+};
+const buildCanaryHeaders = () => ({
+    "cache-control": "no-store",
+    "content-type": "application/json; charset=utf-8",
+});
+export const buildCanaryPayload = (serviceSlug) => {
+    const normalized = normalizeOptionalString(serviceSlug);
+    if (!normalized)
+        throw new Error("serviceSlug is required for canary payloads.");
+    return {
+        ghostgate: "ready",
+        service: normalized,
+    };
+};
+export const createCanaryHandler = (serviceSlug) => {
+    const payload = buildCanaryPayload(serviceSlug);
+    return (_req, res) => {
+        const headers = buildCanaryHeaders();
+        if (res && typeof res === "object") {
+            const response = res;
+            if (typeof response.status === "function" && typeof response.json === "function") {
+                for (const [key, value] of Object.entries(headers)) {
+                    response.setHeader?.(key, value);
+                }
+                response.status(200);
+                return response.json(payload);
+            }
+            if (typeof response.writeHead === "function" && typeof response.end === "function") {
+                response.writeHead(200, headers);
+                return response.end(JSON.stringify(payload));
+            }
+        }
+        return {
+            status: 200,
+            headers,
+            body: payload,
+        };
+    };
+};
+export class GhostAgent {
+    constructor(config = {}) {
+        const normalizedServiceSlug = normalizeOptionalString(config.serviceSlug);
+        this.apiKey = normalizeOptionalString(config.apiKey) ?? null;
+        this.agentId = normalizeOptionalString(config.agentId);
+        this.baseUrl = normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL);
+        this.privateKey = config.privateKey ?? null;
+        this.chainId = config.chainId ?? DEFAULT_CHAIN_ID;
+        this.telemetryServiceSlug = normalizedServiceSlug;
+        this.serviceSlug = normalizedServiceSlug ?? DEFAULT_SERVICE_SLUG;
+        this.creditCost = Number.isFinite(config.creditCost) && (config.creditCost ?? 0) > 0
+            ? Math.trunc(config.creditCost)
+            : DEFAULT_CREDIT_COST;
+    }
+    async connect(apiKey) {
+        const normalizedApiKey = normalizeOptionalString(apiKey) ?? this.apiKey;
+        if (!normalizedApiKey) {
+            throw new Error("connect(apiKey?) requires a non-empty API key via argument or constructor config.");
+        }
+        if (!this.privateKey) {
+            throw new Error("GhostAgent requires a signing privateKey in constructor config to call /api/gate/[...slug].");
+        }
+        const timestamp = BigInt(Math.floor(Date.now() / 1000));
+        const signedPayload = {
+            service: this.serviceSlug,
+            timestamp,
+            nonce: randomUUID().replace(/-/g, ""),
+        };
+        const headerPayload = {
+            service: this.serviceSlug,
+            timestamp: timestamp.toString(),
+            nonce: signedPayload.nonce,
+        };
+        const account = privateKeyToAccount(this.privateKey);
+        const signature = await account.signTypedData({
+            domain: {
+                name: "GhostGate",
+                version: "1",
+                chainId: this.chainId,
+            },
+            types: ACCESS_TYPES,
+            primaryType: "Access",
+            message: signedPayload,
+        });
+        const endpoint = `${this.baseUrl}/api/gate/${encodeURIComponent(this.serviceSlug)}`;
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "x-ghost-sig": signature,
+                "x-ghost-payload": JSON.stringify(headerPayload),
+                "x-ghost-credit-cost": String(this.creditCost),
+                accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+            },
+            cache: "no-store",
+        });
+        const responsePayload = await parsePayload(response);
+        if (response.ok) {
+            this.apiKey = normalizedApiKey;
+        }
+        return {
+            connected: response.ok,
+            apiKeyPrefix: getApiKeyPrefix(normalizedApiKey),
+            endpoint,
+            status: response.status,
+            payload: responsePayload,
+        };
+    }
+    async pulse(input = {}) {
+        const apiKey = normalizeOptionalString(input.apiKey) ?? this.apiKey;
+        const serviceSlug = normalizeOptionalString(input.serviceSlug) ?? this.telemetryServiceSlug;
+        const agentId = normalizeOptionalString(input.agentId) ?? this.agentId ?? deriveAgentId(serviceSlug);
+        assertTelemetryIdentity({ apiKey, agentId, serviceSlug });
+        const endpoint = `${this.baseUrl}/api/telemetry/pulse`;
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+            },
+            body: JSON.stringify({
+                ...(apiKey ? { apiKey } : {}),
+                ...(agentId ? { agentId } : {}),
+                ...(serviceSlug ? { serviceSlug } : {}),
+                ...(toOptionalMetadata(input.metadata) ? { metadata: input.metadata } : {}),
+            }),
+            cache: "no-store",
+        });
+        return {
+            ok: response.ok,
+            endpoint,
+            status: response.status,
+            payload: await parsePayload(response),
+        };
+    }
+    async outcome(input) {
+        const apiKey = normalizeOptionalString(input.apiKey) ?? this.apiKey;
+        const serviceSlug = normalizeOptionalString(input.serviceSlug) ?? this.telemetryServiceSlug;
+        const agentId = normalizeOptionalString(input.agentId) ?? this.agentId ?? deriveAgentId(serviceSlug);
+        const statusCode = normalizeTelemetryStatusCode(input.statusCode);
+        assertTelemetryIdentity({ apiKey, agentId, serviceSlug });
+        const endpoint = `${this.baseUrl}/api/telemetry/outcome`;
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+            },
+            body: JSON.stringify({
+                ...(apiKey ? { apiKey } : {}),
+                ...(agentId ? { agentId } : {}),
+                ...(serviceSlug ? { serviceSlug } : {}),
+                success: Boolean(input.success),
+                ...(statusCode != null ? { statusCode } : {}),
+                ...(toOptionalMetadata(input.metadata) ? { metadata: input.metadata } : {}),
+            }),
+            cache: "no-store",
+        });
+        return {
+            ok: response.ok,
+            endpoint,
+            status: response.status,
+            payload: await parsePayload(response),
+        };
+    }
+    startHeartbeat(options = {}) {
+        const intervalMs = Number.isFinite(options.intervalMs) && (options.intervalMs ?? 0) > 0
+            ? Math.trunc(options.intervalMs)
+            : DEFAULT_HEARTBEAT_INTERVAL_MS;
+        const immediate = options.immediate ?? true;
+        let stopped = false;
+        let inFlight = false;
+        const tick = async () => {
+            if (stopped || inFlight)
+                return;
+            inFlight = true;
+            try {
+                const result = await this.pulse(options);
+                options.onResult?.(result);
+            }
+            catch (error) {
+                options.onError?.(error);
+            }
+            finally {
+                inFlight = false;
+            }
+        };
+        const timer = setInterval(() => {
+            void tick();
+        }, intervalMs);
+        if (immediate) {
+            void tick();
+        }
+        return {
+            stop: () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                clearInterval(timer);
+            },
+        };
+    }
+    get isConnected() {
+        return this.apiKey !== null;
+    }
+    get endpoint() {
+        return `${this.baseUrl}/api/gate`;
+    }
+}
+export class GhostMerchant extends GhostFulfillmentMerchant {
+    constructor(config) {
+        super(config);
+        const normalizedServiceSlug = normalizeOptionalString(config.serviceSlug);
+        if (!normalizedServiceSlug) {
+            throw new Error("GhostMerchant.serviceSlug is required.");
+        }
+        this.merchantServiceSlug = normalizedServiceSlug;
+    }
+    canaryPayload() {
+        return buildCanaryPayload(this.merchantServiceSlug);
+    }
+    canaryHandler() {
+        return createCanaryHandler(this.merchantServiceSlug);
+    }
+}
+export default GhostAgent;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ghostgate/sdk",
+  "version": "0.1.0",
+  "description": "Ghost Protocol Node.js SDK for gate access, fulfillment, telemetry, and canary helpers.",
+  "author": "Ghost Protocol",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://ghostprotocol.cc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ghost-Protocol-Infrastructure/GHOST_PROTOCOL.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Ghost-Protocol-Infrastructure/GHOST_PROTOCOL/issues"
+  },
+  "keywords": [
+    "ghostprotocol",
+    "ghostgate",
+    "sdk",
+    "fulfillment",
+    "eip712",
+    "telemetry",
+    "base"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./fulfillment": {
+      "types": "./dist/fulfillment.d.ts",
+      "import": "./dist/fulfillment.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "viem": "^2.21.0"
+  },
+  "scripts": {
+    "clean": "node -e \"import('node:fs').then(fs => fs.rmSync('dist', { recursive: true, force: true }))\"",
+    "build": "npm run clean && node ../../node_modules/typescript/bin/tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  }
+}