@koralabs/kora-labs-common 6.11.0 → 6.12.0

package/chain/config.js

@@ -26,10 +26,20 @@ const chainConfigFromEnv = (env = process.env) => {
         network: (0, providerConfig_1.normalizeNetwork)((_a = env.NETWORK) !== null && _a !== void 0 ? _a : 'mainnet'),
         koiosBearerToken: ((_b = env.KOIOS_API_BEARER_TOKEN) === null || _b === void 0 ? void 0 : _b.trim()) || undefined,
         blockfrostApiKey: ((_c = env.BLOCKFROST_API_KEY) === null || _c === void 0 ? void 0 : _c.trim()) || undefined,
-        apiHost: ((_d = env.HANDLE_API_ENDPOINT) === null || _d === void 0 ? void 0 : _d.trim()) || undefined
+        apiHost: ((_d = env.HANDLE_API_ENDPOINT) === null || _d === void 0 ? void 0 : _d.trim()) || undefined,
+        apiHeaders: buildApiHeaders(env)
     });
 };
 exports.chainConfigFromEnv = chainConfigFromEnv;
+const buildApiHeaders = (env) => {
+    var _a, _b;
+    const headers = {};
+    if ((_a = env.HANDLE_ME_API_KEY) === null || _a === void 0 ? void 0 : _a.trim())
+        headers['api-key'] = env.HANDLE_ME_API_KEY.trim();
+    if ((_b = env.KORA_USER_AGENT) === null || _b === void 0 ? void 0 : _b.trim())
+        headers['User-Agent'] = env.KORA_USER_AGENT.trim();
+    return Object.keys(headers).length ? headers : undefined;
+};
 /**
  * Factory for the default read-failover provider set: Koios + Blockfrost, mutually redundant.
  */

package/chain/datum/imageDatum.d.ts

@@ -1,7 +1,13 @@
 import { ICreatorDefaults } from '../../handles/interfaces';
-export declare const decodeDatumViaApi: <T>(apiHost: string, datum: string, schema?: Record<string, unknown>, fetcher?: (url: string, init?: any) => Promise<{
-    text: () => Promise<string>;
-}>) => Promise<T>;
+export interface DatumDecodeOptions {
+    /** Extra request headers (e.g. api-key, User-Agent) required by the Handles API /datum endpoint. */
+    headers?: Record<string, string>;
+    /** Injectable fetch for tests; defaults to the runtime global fetch. */
+    fetcher?: (url: string, init?: any) => Promise<{
+        text: () => Promise<string>;
+    }>;
+}
+export declare const decodeDatumViaApi: <T>(apiHost: string, datum: string, schema?: Record<string, unknown>, options?: DatumDecodeOptions) => Promise<T>;
 export declare const decode0xHexToUtf8: (v: unknown) => unknown;
 export declare const normalizeCreatorDefaultTextFields: (creatorDefaults: Record<string, unknown>) => void;
 export interface ImageDatumDetails {
@@ -9,6 +15,4 @@ export interface ImageDatumDetails {
     creatorDefaults?: ICreatorDefaults;
     metadata?: Record<string, unknown>;
 }
-export declare const getImageDataFromDatum: (apiHost: string, datum: string, fetcher?: (url: string, init?: any) => Promise<{
-    text: () => Promise<string>;
-}>) => Promise<ImageDatumDetails>;
+export declare const getImageDataFromDatum: (apiHost: string, datum: string, options?: DatumDecodeOptions) => Promise<ImageDatumDetails>;

package/chain/datum/imageDatum.js

@@ -6,10 +6,12 @@ exports.getImageDataFromDatum = exports.normalizeCreatorDefaultTextFields = expo
 // with a field schema so specific TEXT fields are UTF-8-decoded. This is handle-property-correctness
 // critical — the schema and the 0x-hex fallback below must not drift.
 const defaultFetch = (url, init) => globalThis.fetch(url, init);
-const decodeDatumViaApi = async (apiHost, datum, schema, fetcher = defaultFetch) => {
+const decodeDatumViaApi = async (apiHost, datum, schema, options = {}) => {
+    var _a, _b;
+    const fetcher = (_a = options.fetcher) !== null && _a !== void 0 ? _a : defaultFetch;
     const response = await fetcher(`${apiHost}/datum?from=plutus_data_cbor&to=json`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', ...((_b = options.headers) !== null && _b !== void 0 ? _b : {}) },
         body: JSON.stringify({ cbor: datum, schema })
     });
     const text = await response.text();
@@ -53,7 +55,7 @@ const normalizeCreatorDefaultTextFields = (creatorDefaults) => {
     }
 };
 exports.normalizeCreatorDefaultTextFields = normalizeCreatorDefaultTextFields;
-const getImageDataFromDatum = async (apiHost, datum, fetcher) => {
+const getImageDataFromDatum = async (apiHost, datum, options) => {
     var _a, _b, _c, _d, _e, _f, _g, _h;
     let decodedDatum;
     try {
@@ -70,7 +72,7 @@ const getImageDataFromDatum = async (apiHost, datum, fetcher) => {
                     qr_image: 'string'
                 }
             }
-        }, fetcher);
+        }, options);
     }
     catch (_j) {
         return { image: '' };

package/chain/providerConfig.d.ts

@@ -16,6 +16,12 @@ export interface ChainProviderConfig {
      * critical — do NOT swap it for a local CBOR decode without matching that behavior.
      */
     apiHost?: string;
+    /**
+     * Extra headers sent with the datum-decode POST to `apiHost` (e.g. `api-key`, `User-Agent`).
+     * Required when the Handles API gates `/datum` by api-key — omitting them silently changes
+     * datum-decode behavior. `chainConfigFromEnv` populates these from HANDLE_ME_API_KEY / KORA_USER_AGENT.
+     */
+    apiHeaders?: Record<string, string>;
 }
 export declare const normalizeNetwork: (network: string) => string;
 /** Public api.handle.me host for a network (mainnet has no subdomain prefix). */

package/chain/providers/Blockfrost.js

@@ -118,7 +118,9 @@ class Blockfrost {
             : hex;
         const datum = await this.getAssetDatum(policyId, updateHex);
         if (datum) {
-            return (0, imageDatum_1.getImageDataFromDatum)((_a = this.config.apiHost) !== null && _a !== void 0 ? _a : (0, providerConfig_1.defaultApiHost)(this.config.network), datum);
+            return (0, imageDatum_1.getImageDataFromDatum)((_a = this.config.apiHost) !== null && _a !== void 0 ? _a : (0, providerConfig_1.defaultApiHost)(this.config.network), datum, {
+                headers: this.config.apiHeaders
+            });
         }
         let image = '';
         if ((data === null || data === void 0 ? void 0 : data.onchain_metadata) && (data === null || data === void 0 ? void 0 : data.onchain_metadata.image)) {

package/chain/providers/Koios.js

@@ -180,7 +180,9 @@ class Koios {
         if (metadata && metadata.image)
             image = metadata.image;
         if (datum) {
-            return (0, imageDatum_1.getImageDataFromDatum)((_a = this.config.apiHost) !== null && _a !== void 0 ? _a : (0, providerConfig_1.defaultApiHost)(this.config.network), datum);
+            return (0, imageDatum_1.getImageDataFromDatum)((_a = this.config.apiHost) !== null && _a !== void 0 ? _a : (0, providerConfig_1.defaultApiHost)(this.config.network), datum, {
+                headers: this.config.apiHeaders
+            });
         }
         return { image, metadata };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.11.0",
+    "version": "6.12.0",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",