optropic 1.0.0

package/dist/index.js

@@ -0,0 +1,618 @@
+// src/errors.ts
+var OptropicError = class extends Error {
+  /**
+   * Error code for programmatic handling.
+   */
+  code;
+  /**
+   * HTTP status code (if applicable).
+   */
+  statusCode;
+  /**
+   * Whether this error can be retried.
+   */
+  retryable;
+  /**
+   * Additional details about the error.
+   */
+  details;
+  /**
+   * Request ID for support reference.
+   */
+  requestId;
+  constructor(code, message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "OptropicError";
+    this.code = code;
+    this.statusCode = options?.statusCode;
+    this.retryable = options?.retryable ?? false;
+    this.details = options?.details;
+    this.requestId = options?.requestId;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Create a JSON-serializable representation.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      retryable: this.retryable,
+      details: this.details,
+      requestId: this.requestId
+    };
+  }
+};
+var AuthenticationError = class extends OptropicError {
+  constructor(message = "Authentication failed. Please check your API key.", options) {
+    super(options?.code ?? "INVALID_API_KEY", message, {
+      statusCode: 401,
+      retryable: false,
+      details: options?.details,
+      requestId: options?.requestId
+    });
+    this.name = "AuthenticationError";
+  }
+};
+var InvalidSerialError = class extends OptropicError {
+  /**
+   * The invalid serial that was provided.
+   */
+  serial;
+  constructor(serial, message, options) {
+    super(
+      "INVALID_SERIAL",
+      message ?? `Invalid serial number: "${serial}". Serial must be 1-20 alphanumeric characters.`,
+      {
+        statusCode: 400,
+        retryable: false,
+        details: { serial, ...options?.details },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "InvalidSerialError";
+    this.serial = serial;
+  }
+};
+var InvalidGTINError = class extends OptropicError {
+  /**
+   * The invalid GTIN that was provided.
+   */
+  gtin;
+  constructor(gtin, message, options) {
+    super(
+      "INVALID_GTIN",
+      message ?? `Invalid GTIN: "${gtin}". GTIN must be 8, 12, 13, or 14 digits with valid check digit.`,
+      {
+        statusCode: 400,
+        retryable: false,
+        details: { gtin, ...options?.details },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "InvalidGTINError";
+    this.gtin = gtin;
+  }
+};
+var InvalidCodeError = class extends OptropicError {
+  /**
+   * The invalid code that was provided.
+   */
+  invalidCode;
+  constructor(invalidCode, message, options) {
+    super(
+      "INVALID_CODE_FORMAT",
+      message ?? `Invalid code format: "${invalidCode}". Expected a valid Optropic verification URL or code ID.`,
+      {
+        statusCode: 400,
+        retryable: false,
+        details: { code: invalidCode, ...options?.details },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "InvalidCodeError";
+    this.invalidCode = invalidCode;
+  }
+};
+var RevokedCodeError = class extends OptropicError {
+  /**
+   * The revoked code.
+   */
+  revokedCode;
+  /**
+   * Reason for revocation.
+   */
+  reason;
+  /**
+   * When the code was revoked.
+   */
+  revokedAt;
+  constructor(code, reason, revokedAt, options) {
+    super(
+      "CODE_REVOKED",
+      `Code has been revoked: ${reason}`,
+      {
+        statusCode: 410,
+        retryable: false,
+        details: { code, reason, revokedAt, ...options?.details },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "RevokedCodeError";
+    this.revokedCode = code;
+    this.reason = reason;
+    this.revokedAt = revokedAt;
+  }
+};
+var CodeNotFoundError = class extends OptropicError {
+  /**
+   * The code that was not found.
+   */
+  searchedCode;
+  constructor(code, options) {
+    super(
+      "CODE_NOT_FOUND",
+      `Code not found: "${code}". The code may not exist or may have been entered incorrectly.`,
+      {
+        statusCode: 404,
+        retryable: false,
+        details: { code, ...options?.details },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "CodeNotFoundError";
+    this.searchedCode = code;
+  }
+};
+var BatchNotFoundError = class extends OptropicError {
+  /**
+   * The batch ID that was not found.
+   */
+  batchId;
+  constructor(batchId, options) {
+    super(
+      "BATCH_NOT_FOUND",
+      `Batch not found: "${batchId}".`,
+      {
+        statusCode: 404,
+        retryable: false,
+        details: { batchId, ...options?.details },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "BatchNotFoundError";
+    this.batchId = batchId;
+  }
+};
+var RateLimitedError = class extends OptropicError {
+  /**
+   * Seconds until rate limit resets.
+   */
+  retryAfter;
+  /**
+   * Current rate limit (requests per period).
+   */
+  limit;
+  /**
+   * Remaining requests in current period.
+   */
+  remaining;
+  constructor(retryAfter, options) {
+    super(
+      "RATE_LIMITED",
+      `Rate limit exceeded. Please retry after ${retryAfter} seconds.`,
+      {
+        statusCode: 429,
+        retryable: true,
+        details: {
+          retryAfter,
+          limit: options?.limit,
+          remaining: options?.remaining,
+          ...options?.details
+        },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "RateLimitedError";
+    this.retryAfter = retryAfter;
+    this.limit = options?.limit ?? 0;
+    this.remaining = options?.remaining ?? 0;
+  }
+};
+var QuotaExceededError = class extends OptropicError {
+  /**
+   * Current quota limit.
+   */
+  quotaLimit;
+  /**
+   * Quota used.
+   */
+  quotaUsed;
+  /**
+   * When quota resets (ISO 8601).
+   */
+  resetsAt;
+  constructor(quotaLimit, quotaUsed, resetsAt, options) {
+    super(
+      "QUOTA_EXCEEDED",
+      `Monthly quota exceeded (${quotaUsed}/${quotaLimit}). Resets at ${resetsAt}.`,
+      {
+        statusCode: 402,
+        retryable: false,
+        details: { quotaLimit, quotaUsed, resetsAt, ...options?.details },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "QuotaExceededError";
+    this.quotaLimit = quotaLimit;
+    this.quotaUsed = quotaUsed;
+    this.resetsAt = resetsAt;
+  }
+};
+var NetworkError = class extends OptropicError {
+  constructor(message = "Network error occurred. Please check your connection.", options) {
+    super("NETWORK_ERROR", message, {
+      statusCode: void 0,
+      retryable: true,
+      details: options?.details,
+      requestId: options?.requestId,
+      cause: options?.cause
+    });
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends OptropicError {
+  /**
+   * Timeout duration in milliseconds.
+   */
+  timeoutMs;
+  constructor(timeoutMs, options) {
+    super(
+      "TIMEOUT",
+      `Request timed out after ${timeoutMs}ms. Please try again.`,
+      {
+        statusCode: 408,
+        retryable: true,
+        details: { timeoutMs, ...options?.details },
+        requestId: options?.requestId
+      }
+    );
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var ServiceUnavailableError = class extends OptropicError {
+  constructor(message = "Service temporarily unavailable. Please try again later.", options) {
+    super("SERVICE_UNAVAILABLE", message, {
+      statusCode: 503,
+      retryable: true,
+      details: { retryAfter: options?.retryAfter, ...options?.details },
+      requestId: options?.requestId
+    });
+    this.name = "ServiceUnavailableError";
+  }
+};
+function createErrorFromResponse(statusCode, body) {
+  const code = body.code ?? "UNKNOWN_ERROR";
+  const message = body.message ?? "An unknown error occurred";
+  const { details, requestId } = body;
+  switch (code) {
+    case "INVALID_API_KEY":
+    case "EXPIRED_API_KEY":
+    case "INSUFFICIENT_PERMISSIONS":
+      return new AuthenticationError(message, { code, details, requestId });
+    case "INVALID_SERIAL":
+      return new InvalidSerialError(
+        details?.serial ?? "",
+        message,
+        { details, requestId }
+      );
+    case "INVALID_GTIN":
+      return new InvalidGTINError(
+        details?.gtin ?? "",
+        message,
+        { details, requestId }
+      );
+    case "INVALID_CODE_FORMAT":
+      return new InvalidCodeError(
+        details?.code ?? "",
+        message,
+        { details, requestId }
+      );
+    case "CODE_NOT_FOUND":
+      return new CodeNotFoundError(
+        details?.code ?? "",
+        { details, requestId }
+      );
+    case "BATCH_NOT_FOUND":
+      return new BatchNotFoundError(
+        details?.batchId ?? "",
+        { details, requestId }
+      );
+    case "CODE_REVOKED":
+      return new RevokedCodeError(
+        details?.code ?? "",
+        details?.reason ?? "Unknown reason",
+        details?.revokedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+        { details, requestId }
+      );
+    case "RATE_LIMITED":
+      return new RateLimitedError(
+        details?.retryAfter ?? 60,
+        {
+          limit: details?.limit,
+          remaining: details?.remaining,
+          details,
+          requestId
+        }
+      );
+    case "QUOTA_EXCEEDED":
+      return new QuotaExceededError(
+        details?.quotaLimit ?? 0,
+        details?.quotaUsed ?? 0,
+        details?.resetsAt ?? "",
+        { details, requestId }
+      );
+    case "NETWORK_ERROR":
+      return new NetworkError(message, { details, requestId });
+    case "TIMEOUT":
+      return new TimeoutError(
+        details?.timeoutMs ?? 3e4,
+        { details, requestId }
+      );
+    case "SERVICE_UNAVAILABLE":
+      return new ServiceUnavailableError(message, {
+        retryAfter: details?.retryAfter,
+        details,
+        requestId
+      });
+    default:
+      return new OptropicError(code, message, {
+        statusCode,
+        retryable: statusCode >= 500,
+        details,
+        requestId
+      });
+  }
+}
+
+// src/resources/assets.ts
+var AssetsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  async create(params) {
+    return this.request({ method: "POST", path: "/v1/assets", body: params });
+  }
+  async list(params) {
+    const query = params ? this.buildQuery(params) : "";
+    return this.request({ method: "GET", path: `/v1/assets${query}` });
+  }
+  async get(assetId) {
+    return this.request({ method: "GET", path: `/v1/assets/${encodeURIComponent(assetId)}` });
+  }
+  async verify(assetId) {
+    return this.request({ method: "GET", path: `/v1/assets/${encodeURIComponent(assetId)}/verify` });
+  }
+  async revoke(assetId, reason) {
+    return this.request({
+      method: "POST",
+      path: `/v1/assets/${encodeURIComponent(assetId)}/revoke`,
+      body: reason ? { reason } : void 0
+    });
+  }
+  async batchCreate(params) {
+    return this.request({ method: "POST", path: "/v1/assets/batch", body: params });
+  }
+  buildQuery(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== void 0);
+    if (entries.length === 0) return "";
+    return "?" + entries.map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`).join("&");
+  }
+};
+
+// src/resources/keys.ts
+var KeysResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  async create(params) {
+    return this.request({ method: "POST", path: "/v1/keys", body: params });
+  }
+  async list() {
+    return this.request({ method: "GET", path: "/v1/keys" });
+  }
+  async revoke(keyId) {
+    await this.request({ method: "DELETE", path: `/v1/keys/${encodeURIComponent(keyId)}` });
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.optropic.com";
+var DEFAULT_TIMEOUT = 3e4;
+var SDK_VERSION = "1.0.0";
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  baseDelay: 1e3,
+  maxDelay: 1e4
+};
+var OptropicClient = class {
+  config;
+  baseUrl;
+  retryConfig;
+  assets;
+  keys;
+  constructor(config) {
+    if (!config.apiKey || !this.isValidApiKey(config.apiKey)) {
+      throw new AuthenticationError(
+        "Invalid API key format. Expected format: optr_live_xxx or optr_test_xxx"
+      );
+    }
+    this.config = {
+      ...config,
+      timeout: config.timeout ?? DEFAULT_TIMEOUT
+    };
+    if (config.baseUrl) {
+      this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    } else {
+      this.baseUrl = DEFAULT_BASE_URL;
+    }
+    this.retryConfig = {
+      ...DEFAULT_RETRY_CONFIG,
+      ...config.retry
+    };
+    const boundRequest = this.request.bind(this);
+    this.assets = new AssetsResource(boundRequest);
+    this.keys = new KeysResource(boundRequest);
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // PRIVATE METHODS
+  // ─────────────────────────────────────────────────────────────────────────
+  isValidApiKey(apiKey) {
+    return /^optr_(live|test)_[a-zA-Z0-9_-]{20,}$/.test(apiKey);
+  }
+  async request(options) {
+    const { method, path, body, headers = {}, timeout = this.config.timeout } = options;
+    const url = `${this.baseUrl}${path}`;
+    const requestHeaders = {
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      "x-api-key": this.config.apiKey,
+      "X-SDK-Version": SDK_VERSION,
+      "X-SDK-Language": "typescript",
+      ...this.config.headers,
+      ...headers
+    };
+    let lastError = null;
+    let attempt = 0;
+    while (attempt <= this.retryConfig.maxRetries) {
+      try {
+        const response = await this.executeRequest(
+          url,
+          method,
+          requestHeaders,
+          body,
+          timeout
+        );
+        return response;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof OptropicError && !error.retryable) {
+          throw error;
+        }
+        if (attempt >= this.retryConfig.maxRetries) {
+          throw error;
+        }
+        const delay = Math.min(
+          this.retryConfig.baseDelay * Math.pow(2, attempt),
+          this.retryConfig.maxDelay
+        );
+        if (error instanceof RateLimitedError) {
+          await this.sleep(error.retryAfter * 1e3);
+        } else {
+          await this.sleep(delay);
+        }
+        attempt++;
+      }
+    }
+    throw lastError ?? new OptropicError("UNKNOWN_ERROR", "Request failed");
+  }
+  async executeRequest(url, method, headers, body, timeout) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const requestId = response.headers.get("x-request-id") ?? "";
+      if (!response.ok) {
+        let errorBody;
+        try {
+          const json2 = await response.json();
+          const parsed = json2.error ?? json2;
+          errorBody = {
+            code: parsed?.code ?? "UNKNOWN_ERROR",
+            message: parsed?.message ?? `HTTP ${response.status}: ${response.statusText}`,
+            details: parsed?.details
+          };
+        } catch {
+          errorBody = {
+            code: "UNKNOWN_ERROR",
+            message: `HTTP ${response.status}: ${response.statusText}`
+          };
+        }
+        throw createErrorFromResponse(response.status, {
+          // Justified: Error code string from API may not match SDK's ErrorCode enum exactly
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          code: errorBody.code,
+          message: errorBody.message,
+          details: errorBody.details,
+          requestId
+        });
+      }
+      const json = await response.json();
+      if (json.error) {
+        throw createErrorFromResponse(response.status, {
+          // Justified: Error code string from API may not match SDK's ErrorCode enum exactly
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          code: json.error.code,
+          message: json.error.message,
+          details: json.error.details,
+          requestId: json.requestId
+        });
+      }
+      return json.data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof OptropicError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new TimeoutError(timeout);
+        }
+        throw new NetworkError(error.message, { cause: error });
+      }
+      throw new OptropicError("UNKNOWN_ERROR", "An unexpected error occurred", {
+        retryable: false
+      });
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+function createClient(config) {
+  return new OptropicClient(config);
+}
+
+// src/index.ts
+var SDK_VERSION2 = "1.0.0";
+export {
+  AssetsResource,
+  AuthenticationError,
+  BatchNotFoundError,
+  CodeNotFoundError,
+  InvalidCodeError,
+  InvalidGTINError,
+  InvalidSerialError,
+  KeysResource,
+  NetworkError,
+  OptropicClient,
+  OptropicError,
+  QuotaExceededError,
+  RateLimitedError,
+  RevokedCodeError,
+  SDK_VERSION2 as SDK_VERSION,
+  ServiceUnavailableError,
+  TimeoutError,
+  createClient
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "optropic",
+  "version": "1.0.0",
+  "description": "Official Optropic SDK for TypeScript and JavaScript",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "optropic",
+    "authentication",
+    "anti-counterfeit",
+    "product-verification",
+    "qr-code",
+    "gs1",
+    "gtin",
+    "serialization"
+  ],
+  "author": "Optropic GmbH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/optropic/optropic-node.git"
+  },
+  "homepage": "https://docs.optropic.com/sdk/typescript",
+  "bugs": {
+    "url": "https://github.com/optropic/optropic-node/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.3",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {},
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false
+}