@hark-protocol/sdk 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @hark-protocol/sdk
+
+Publisher and advertiser clients for [Hark Protocol](https://github.com/SiddharthaMadhav/ETHOnline-2026) -
+an open intent-advertising protocol where platforms publish temporary,
+privacy-preserving user intent and autonomous advertising agents pay through
+x402 on Hedera to reach matching users.
+
+## Publisher client
+
+Authenticated with a publisher secret - never expose this in browser code.
+
+```ts
+import { HarkPublisherClient } from "@hark-protocol/sdk";
+
+const hark = new HarkPublisherClient({
+  baseUrl: "https://your-hark-api.example.com",
+  publisherKey: process.env.DEMO_PUBLISHER_KEY!,
+});
+
+const intent = await hark.intents.create({
+  subjectRef: "user-001",
+  placementIds: ["plc_..."],
+  topics: [{ id: "electronics.computer.laptop", confidence: 0.91 }],
+  semanticSummary: "Looking for a lightweight computer for coding.",
+});
+
+await hark.intents.update(intent.id, { expiresInSeconds: 2592000 });
+await hark.intents.revoke(intent.id, "user_requested");
+const feed = await hark.feed.get("user-001");
+await hark.deliveries.markServed(feed[0].id);
+```
+
+## Advertiser client
+
+Every method except `reach()` is free - no Hark API key required.
+
+```ts
+import { HarkAdvertiserClient } from "@hark-protocol/sdk";
+
+const hark = new HarkAdvertiserClient({ baseUrl: "https://your-hark-api.example.com" });
+
+const discovery = await hark.discovery.get();
+const opportunities = await hark.opportunities.list(campaignId);
+```
+
+`reach()` is x402-gated: pass an x402-capable `fetch` (e.g. `@x402/fetch`'s
+`wrapFetchWithPayment`) as the client's `fetch` option. This client never
+owns or touches Hedera keys itself.
+
+```ts
+const hark = new HarkAdvertiserClient({ baseUrl, fetch: fetchWithPayment });
+const { confirmation, transactionId } = await hark.reach({ opportunityId, campaignId });
+```
+
+Part of the [Hark Protocol](https://github.com/SiddharthaMadhav/ETHOnline-2026)
+monorepo. See that repo for the full protocol spec, API, and demo apps.

package/dist/advertiser.d.ts

@@ -0,0 +1,61 @@
+import { type HarkOpportunity, type Campaign, type CreateCampaignInput, type ReachConfirmation } from "@hark-protocol/protocol";
+import { type HarkClientConfig } from "./client.js";
+export type DiscoveryDocument = {
+    name: string;
+    protocolVersion: string;
+    description: string;
+    network: string;
+    paymentProtocol: string;
+    asset: string;
+    services: Array<{
+        name: string;
+        method: string;
+        path: string;
+        paid: boolean;
+    }>;
+};
+export type TopicDefinition = {
+    id: string;
+    label: string;
+    parentId?: string;
+};
+export type ReachParams = {
+    opportunityId: string;
+    campaignId: string;
+    /** Defaults to a random UUID (CLAUDE.md section 19). */
+    idempotencyKey?: string;
+};
+export type ReachResult = {
+    confirmation: ReachConfirmation;
+    /** Settled Hedera transaction id, decoded from the x402 payment-response header, when present. */
+    transactionId?: string;
+};
+/**
+ * Advertiser-side client (CLAUDE.md section 20). Every method except
+ * `reach()` is free and requires no Hark API key at all (CLAUDE.md section
+ * 2.8) - it needs no publisher secret, only whatever `fetch` you pass in.
+ *
+ * `reach()` is x402-gated: pass an x402-capable `fetch` in the constructor
+ * (e.g. `@x402/fetch`'s `wrapFetchWithPayment`). This client never owns or
+ * touches Hedera keys itself - it only calls whatever `fetch` it was given.
+ */
+export declare class HarkAdvertiserClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(config: HarkClientConfig);
+    discovery: {
+        get: () => Promise<DiscoveryDocument>;
+    };
+    topics: {
+        list: () => Promise<TopicDefinition[]>;
+    };
+    campaigns: {
+        create: (input: CreateCampaignInput) => Promise<Campaign>;
+        list: () => Promise<Campaign[]>;
+    };
+    opportunities: {
+        list: (campaignId?: string) => Promise<HarkOpportunity[]>;
+    };
+    reach: (params: ReachParams) => Promise<ReachResult>;
+}
+//# sourceMappingURL=advertiser.d.ts.map

package/dist/advertiser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertiser.d.ts","sourceRoot":"","sources":["../src/advertiser.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAiC,KAAK,gBAAgB,EAAkB,MAAM,aAAa,CAAC;AAEnG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAChF,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,YAAY,EAAE,iBAAiB,CAAC;IAChC,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,MAAM,EAAE,gBAAgB;IAKpC,SAAS;mBACQ,OAAO,CAAC,iBAAiB,CAAC;MAIzC;IAEF,MAAM;oBACY,OAAO,CAAC,eAAe,EAAE,CAAC;MAQ1C;IAEF,SAAS;wBACe,mBAAmB,KAAG,OAAO,CAAC,QAAQ,CAAC;oBAU7C,OAAO,CAAC,QAAQ,EAAE,CAAC;MAInC;IAEF,aAAa;4BACe,MAAM,KAAG,OAAO,CAAC,eAAe,EAAE,CAAC;MAM7D;IAEF,KAAK,GAAU,QAAQ,WAAW,KAAG,OAAO,CAAC,WAAW,CAAC,CAoBvD;CACH"}

package/dist/advertiser.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { decodePaymentResponseHeader } from "@x402/core/http";
+import { harkOpportunitySchema, campaignSchema, createCampaignInputSchema, reachConfirmationSchema, } from "@hark-protocol/protocol";
+import { normalizeBaseUrl, requestJson } from "./client.js";
+/**
+ * Advertiser-side client (CLAUDE.md section 20). Every method except
+ * `reach()` is free and requires no Hark API key at all (CLAUDE.md section
+ * 2.8) - it needs no publisher secret, only whatever `fetch` you pass in.
+ *
+ * `reach()` is x402-gated: pass an x402-capable `fetch` in the constructor
+ * (e.g. `@x402/fetch`'s `wrapFetchWithPayment`). This client never owns or
+ * touches Hedera keys itself - it only calls whatever `fetch` it was given.
+ */
+export class HarkAdvertiserClient {
+    baseUrl;
+    fetchImpl;
+    constructor(config) {
+        this.baseUrl = normalizeBaseUrl(config.baseUrl);
+        this.fetchImpl = config.fetch ?? fetch;
+    }
+    discovery = {
+        get: async () => {
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/.well-known/hark.json`);
+            return data;
+        },
+    };
+    topics = {
+        list: async () => {
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/topics`);
+            return z
+                .object({
+                items: z.array(z.object({ id: z.string(), label: z.string(), parentId: z.string().optional() })),
+            })
+                .parse(data).items;
+        },
+    };
+    campaigns = {
+        create: async (input) => {
+            createCampaignInputSchema.parse(input);
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/campaigns`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(input),
+            });
+            return campaignSchema.parse(data);
+        },
+        list: async () => {
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/campaigns`);
+            return z.object({ items: z.array(campaignSchema) }).parse(data).items;
+        },
+    };
+    opportunities = {
+        list: async (campaignId) => {
+            const url = new URL(`${this.baseUrl}/v1/opportunities`);
+            if (campaignId)
+                url.searchParams.set("campaignId", campaignId);
+            const { data } = await requestJson(this.fetchImpl, url.toString());
+            return z.object({ items: z.array(harkOpportunitySchema) }).parse(data).items;
+        },
+    };
+    reach = async (params) => {
+        const idempotencyKey = params.idempotencyKey ?? crypto.randomUUID();
+        const { data, response } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/reach`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-hark-idempotency-key": idempotencyKey },
+            body: JSON.stringify({ opportunityId: params.opportunityId, campaignId: params.campaignId }),
+        });
+        const paymentResponseHeader = response.headers.get("payment-response") ?? response.headers.get("x-payment-response");
+        let transactionId;
+        if (paymentResponseHeader) {
+            try {
+                transactionId = decodePaymentResponseHeader(paymentResponseHeader).transaction;
+            }
+            catch {
+                transactionId = undefined;
+            }
+        }
+        return { confirmation: reachConfirmationSchema.parse(data), transactionId };
+    };
+}
+//# sourceMappingURL=advertiser.js.map

package/dist/advertiser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertiser.js","sourceRoot":"","sources":["../src/advertiser.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared HTTP plumbing for both Hark clients (CLAUDE.md section 20).
+ * Deliberately has no Hedera/x402 signing logic of its own - callers pass in
+ * whatever `fetch` they want (plain fetch for free endpoints, an x402-wrapped
+ * fetch for the advertiser client's paid `reach()`).
+ */
+export type HarkFetch = typeof fetch;
+export type HarkClientConfig = {
+    baseUrl: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: HarkFetch;
+};
+/** Mirrors the error contract in CLAUDE.md section 39. */
+export declare class HarkApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+export declare function normalizeBaseUrl(baseUrl: string): string;
+/**
+ * Performs the request and returns the parsed JSON body alongside the raw
+ * `Response` (needed by `reach()` to read the x402 payment-response header).
+ * Throws `HarkApiError` for any non-2xx response, using the error body's
+ * `error.message`/`error.code` when present.
+ */
+export declare function requestJson(fetchImpl: HarkFetch, url: string, init?: RequestInit): Promise<{
+    data: unknown;
+    response: Response;
+}>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;AAErC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,0DAA0D;AAC1D,qBAAa,YAAa,SAAQ,KAAK;aAEnB,MAAM,EAAE,MAAM;aAEd,IAAI,CAAC,EAAE,MAAM;gBAFb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA;CAIhC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,CAYhD"}

package/dist/client.js

@@ -0,0 +1,29 @@
+/** Mirrors the error contract in CLAUDE.md section 39. */
+export class HarkApiError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+/**
+ * Performs the request and returns the parsed JSON body alongside the raw
+ * `Response` (needed by `reach()` to read the x402 payment-response header).
+ * Throws `HarkApiError` for any non-2xx response, using the error body's
+ * `error.message`/`error.code` when present.
+ */
+export async function requestJson(fetchImpl, url, init = {}) {
+    const response = await fetchImpl(url, init);
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) {
+        const errorBody = data;
+        throw new HarkApiError(response.status, errorBody?.error?.message ?? `Hark API error: ${response.status}`, errorBody?.error?.code);
+    }
+    return { data, response };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAcA,0DAA0D;AAC1D,MAAM,OAAO,YAAa,SAAQ,KAAK;IAEnB;IAEA;IAHlB,YACkB,MAAc,EAC9B,OAAe,EACC,IAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAQ;QAEd,SAAI,GAAJ,IAAI,CAAS;IAG/B,CAAC;CACF;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAAoB,EACpB,GAAW,EACX,OAAoB,EAAE;IAEtB,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,IAAuD,CAAC;QAC1E,MAAM,IAAI,YAAY,CACpB,QAAQ,CAAC,MAAM,EACf,SAAS,EAAE,KAAK,EAAE,OAAO,IAAI,mBAAmB,QAAQ,CAAC,MAAM,EAAE,EACjE,SAAS,EAAE,KAAK,EAAE,IAAI,CACvB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./client.js";
+export * from "./publisher.js";
+export * from "./advertiser.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./client.js";
+export * from "./publisher.js";
+export * from "./advertiser.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/publisher.d.ts

@@ -0,0 +1,30 @@
+import { type CreateIntentInput, type UpdateIntentInput, type RevokeReason, type HarkIntent, type FeedDelivery } from "@hark-protocol/protocol";
+import { type HarkClientConfig } from "./client.js";
+export type HarkPublisherClientConfig = HarkClientConfig & {
+    /** The publisher's own secret (CLAUDE.md section 11) - sent as a Bearer token. */
+    publisherKey: string;
+};
+/**
+ * Publisher-side client (CLAUDE.md section 20). Every call is authenticated
+ * with the publisher's own secret - never expose an instance of this client,
+ * or the key passed into it, to untrusted/browser code.
+ */
+export declare class HarkPublisherClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly publisherKey;
+    constructor(config: HarkPublisherClientConfig);
+    private authHeaders;
+    intents: {
+        create: (input: CreateIntentInput) => Promise<HarkIntent>;
+        update: (intentId: string, input: UpdateIntentInput) => Promise<HarkIntent>;
+        revoke: (intentId: string, reason?: RevokeReason) => Promise<HarkIntent>;
+    };
+    feed: {
+        get: (subjectRef: string) => Promise<FeedDelivery[]>;
+    };
+    deliveries: {
+        markServed: (deliveryId: string) => Promise<FeedDelivery>;
+    };
+}
+//# sourceMappingURL=publisher.d.ts.map

package/dist/publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.d.ts","sourceRoot":"","sources":["../src/publisher.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAiC,KAAK,gBAAgB,EAAkB,MAAM,aAAa,CAAC;AAEnG,MAAM,MAAM,yBAAyB,GAAG,gBAAgB,GAAG;IACzD,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,EAAE,yBAAyB;IAM7C,OAAO,CAAC,WAAW;IAInB,OAAO;wBACiB,iBAAiB,KAAG,OAAO,CAAC,UAAU,CAAC;2BAUpC,MAAM,SAAS,iBAAiB,KAAG,OAAO,CAAC,UAAU,CAAC;2BActD,MAAM,WAAU,YAAY,KAAa,OAAO,CAAC,UAAU,CAAC;MAYrF;IAEF,IAAI;0BACsB,MAAM,KAAG,OAAO,CAAC,YAAY,EAAE,CAAC;MAQxD;IAEF,UAAU;iCACuB,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC;MAQ7D;CACH"}

package/dist/publisher.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { createIntentInputSchema, updateIntentInputSchema, harkIntentSchema, feedDeliverySchema, } from "@hark-protocol/protocol";
+import { normalizeBaseUrl, requestJson } from "./client.js";
+/**
+ * Publisher-side client (CLAUDE.md section 20). Every call is authenticated
+ * with the publisher's own secret - never expose an instance of this client,
+ * or the key passed into it, to untrusted/browser code.
+ */
+export class HarkPublisherClient {
+    baseUrl;
+    fetchImpl;
+    publisherKey;
+    constructor(config) {
+        this.baseUrl = normalizeBaseUrl(config.baseUrl);
+        this.fetchImpl = config.fetch ?? fetch;
+        this.publisherKey = config.publisherKey;
+    }
+    authHeaders() {
+        return { authorization: `Bearer ${this.publisherKey}` };
+    }
+    intents = {
+        create: async (input) => {
+            createIntentInputSchema.parse(input);
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/intents`, {
+                method: "POST",
+                headers: { "content-type": "application/json", ...this.authHeaders() },
+                body: JSON.stringify(input),
+            });
+            return harkIntentSchema.parse(data);
+        },
+        update: async (intentId, input) => {
+            updateIntentInputSchema.parse(input);
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/intents/${encodeURIComponent(intentId)}`, {
+                method: "PATCH",
+                headers: { "content-type": "application/json", ...this.authHeaders() },
+                body: JSON.stringify(input),
+            });
+            return harkIntentSchema.parse(data);
+        },
+        revoke: async (intentId, reason = "other") => {
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/intents/${encodeURIComponent(intentId)}`, {
+                method: "DELETE",
+                headers: { "content-type": "application/json", ...this.authHeaders() },
+                body: JSON.stringify({ reason }),
+            });
+            return harkIntentSchema.parse(data);
+        },
+    };
+    feed = {
+        get: async (subjectRef) => {
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/feed/${encodeURIComponent(subjectRef)}`, { headers: this.authHeaders() });
+            return z.object({ items: z.array(feedDeliverySchema) }).parse(data).items;
+        },
+    };
+    deliveries = {
+        markServed: async (deliveryId) => {
+            const { data } = await requestJson(this.fetchImpl, `${this.baseUrl}/v1/deliveries/${encodeURIComponent(deliveryId)}/served`, { method: "POST", headers: this.authHeaders() });
+            return feedDeliverySchema.parse(data);
+        },
+    };
+}
+//# sourceMappingURL=publisher.js.map

package/dist/publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.js","sourceRoot":"","sources":["../src/publisher.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@hark-protocol/sdk",
+  "version": "0.1.0",
+  "description": "Publisher and advertiser clients for the Hark Protocol - intent advertising with x402 payments on Hedera.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SiddharthaMadhav/ETHOnline-2026.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": ["hark-protocol", "hedera", "x402", "intent-advertising"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hark-protocol/protocol": "workspace:*",
+    "@x402/core": "2.25.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}