@hark-protocol/protocol 0.1.0

package/dist/schemas/delivery.d.ts

@@ -0,0 +1,162 @@
+import { z } from "zod";
+export declare const deliveryStatusSchema: z.ZodEnum<["queued", "served", "dismissed"]>;
+export type DeliveryStatus = z.infer<typeof deliveryStatusSchema>;
+export declare const deliveryPaymentSchema: z.ZodObject<{
+    network: z.ZodLiteral<"hedera:testnet">;
+    asset: z.ZodLiteral<"0.0.0">;
+    amountTinybar: z.ZodString;
+    transactionId: z.ZodOptional<z.ZodString>;
+    payerAccountId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    network: "hedera:testnet";
+    asset: "0.0.0";
+    amountTinybar: string;
+    transactionId?: string | undefined;
+    payerAccountId?: string | undefined;
+}, {
+    network: "hedera:testnet";
+    asset: "0.0.0";
+    amountTinybar: string;
+    transactionId?: string | undefined;
+    payerAccountId?: string | undefined;
+}>;
+export type DeliveryPayment = z.infer<typeof deliveryPaymentSchema>;
+/**
+ * Internal Hark delivery record (CLAUDE.md section 9).
+ * `intentId` and `subjectRef` are internal-only and MUST NOT be serialized
+ * to advertiser-facing responses.
+ */
+export declare const deliverySchema: z.ZodObject<{
+    id: z.ZodString;
+    campaignId: z.ZodString;
+    publisherId: z.ZodString;
+    placementId: z.ZodString;
+    intentId: z.ZodString;
+    subjectRef: z.ZodString;
+    status: z.ZodEnum<["queued", "served", "dismissed"]>;
+    payment: z.ZodObject<{
+        network: z.ZodLiteral<"hedera:testnet">;
+        asset: z.ZodLiteral<"0.0.0">;
+        amountTinybar: z.ZodString;
+        transactionId: z.ZodOptional<z.ZodString>;
+        payerAccountId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        network: "hedera:testnet";
+        asset: "0.0.0";
+        amountTinybar: string;
+        transactionId?: string | undefined;
+        payerAccountId?: string | undefined;
+    }, {
+        network: "hedera:testnet";
+        asset: "0.0.0";
+        amountTinybar: string;
+        transactionId?: string | undefined;
+        payerAccountId?: string | undefined;
+    }>;
+    createdAt: z.ZodString;
+    servedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "queued" | "served" | "dismissed";
+    id: string;
+    createdAt: string;
+    publisherId: string;
+    subjectRef: string;
+    campaignId: string;
+    placementId: string;
+    intentId: string;
+    payment: {
+        network: "hedera:testnet";
+        asset: "0.0.0";
+        amountTinybar: string;
+        transactionId?: string | undefined;
+        payerAccountId?: string | undefined;
+    };
+    servedAt?: string | undefined;
+}, {
+    status: "queued" | "served" | "dismissed";
+    id: string;
+    createdAt: string;
+    publisherId: string;
+    subjectRef: string;
+    campaignId: string;
+    placementId: string;
+    intentId: string;
+    payment: {
+        network: "hedera:testnet";
+        asset: "0.0.0";
+        amountTinybar: string;
+        transactionId?: string | undefined;
+        payerAccountId?: string | undefined;
+    };
+    servedAt?: string | undefined;
+}>;
+export type Delivery = z.infer<typeof deliverySchema>;
+/**
+ * Publisher-facing delivery view returned from GET /v1/feed/:subjectRef.
+ * Excludes internal intentId (publisher already knows its own subjectRef,
+ * but the internal Hark intent database id is never exposed).
+ */
+export declare const feedDeliverySchema: z.ZodObject<Omit<{
+    id: z.ZodString;
+    campaignId: z.ZodString;
+    publisherId: z.ZodString;
+    placementId: z.ZodString;
+    intentId: z.ZodString;
+    subjectRef: z.ZodString;
+    status: z.ZodEnum<["queued", "served", "dismissed"]>;
+    payment: z.ZodObject<{
+        network: z.ZodLiteral<"hedera:testnet">;
+        asset: z.ZodLiteral<"0.0.0">;
+        amountTinybar: z.ZodString;
+        transactionId: z.ZodOptional<z.ZodString>;
+        payerAccountId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        network: "hedera:testnet";
+        asset: "0.0.0";
+        amountTinybar: string;
+        transactionId?: string | undefined;
+        payerAccountId?: string | undefined;
+    }, {
+        network: "hedera:testnet";
+        asset: "0.0.0";
+        amountTinybar: string;
+        transactionId?: string | undefined;
+        payerAccountId?: string | undefined;
+    }>;
+    createdAt: z.ZodString;
+    servedAt: z.ZodOptional<z.ZodString>;
+}, "intentId">, "strip", z.ZodTypeAny, {
+    status: "queued" | "served" | "dismissed";
+    id: string;
+    createdAt: string;
+    publisherId: string;
+    subjectRef: string;
+    campaignId: string;
+    placementId: string;
+    payment: {
+        network: "hedera:testnet";
+        asset: "0.0.0";
+        amountTinybar: string;
+        transactionId?: string | undefined;
+        payerAccountId?: string | undefined;
+    };
+    servedAt?: string | undefined;
+}, {
+    status: "queued" | "served" | "dismissed";
+    id: string;
+    createdAt: string;
+    publisherId: string;
+    subjectRef: string;
+    campaignId: string;
+    placementId: string;
+    payment: {
+        network: "hedera:testnet";
+        asset: "0.0.0";
+        amountTinybar: string;
+        transactionId?: string | undefined;
+        payerAccountId?: string | undefined;
+    };
+    servedAt?: string | undefined;
+}>;
+export type FeedDelivery = z.infer<typeof feedDeliverySchema>;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/schemas/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/schemas/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,oBAAoB,8CAA4C,CAAC;AAC9E,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;EAMhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA0C,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/schemas/delivery.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { tinybarAmountSchema } from "./campaign.js";
+import { HEDERA_TESTNET_NETWORK, HBAR_ASSET_ID } from "../constants.js";
+export const deliveryStatusSchema = z.enum(["queued", "served", "dismissed"]);
+export const deliveryPaymentSchema = z.object({
+    network: z.literal(HEDERA_TESTNET_NETWORK),
+    asset: z.literal(HBAR_ASSET_ID),
+    amountTinybar: tinybarAmountSchema,
+    transactionId: z.string().optional(),
+    payerAccountId: z.string().optional(),
+});
+/**
+ * Internal Hark delivery record (CLAUDE.md section 9).
+ * `intentId` and `subjectRef` are internal-only and MUST NOT be serialized
+ * to advertiser-facing responses.
+ */
+export const deliverySchema = z.object({
+    id: z.string(),
+    campaignId: z.string(),
+    publisherId: z.string(),
+    placementId: z.string(),
+    intentId: z.string(),
+    subjectRef: z.string(),
+    status: deliveryStatusSchema,
+    payment: deliveryPaymentSchema,
+    createdAt: z.string().datetime(),
+    servedAt: z.string().datetime().optional(),
+});
+/**
+ * Publisher-facing delivery view returned from GET /v1/feed/:subjectRef.
+ * Excludes internal intentId (publisher already knows its own subjectRef,
+ * but the internal Hark intent database id is never exposed).
+ */
+export const feedDeliverySchema = deliverySchema.omit({ intentId: true });
+//# sourceMappingURL=delivery.js.map

package/dist/schemas/delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../../src/schemas/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAExE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;AAG9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC;IAC1C,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;IAC/B,aAAa,EAAE,mBAAmB;IAClC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,MAAM,EAAE,oBAAoB;IAC5B,OAAO,EAAE,qBAAqB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,cAAc,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC"}

package/dist/schemas/intent.d.ts

@@ -0,0 +1,244 @@
+import { z } from "zod";
+export declare const intentTopicSchema: z.ZodObject<{
+    id: z.ZodEffects<z.ZodString, string, string>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    confidence?: number | undefined;
+}, {
+    id: string;
+    confidence?: number | undefined;
+}>;
+export type IntentTopic = z.infer<typeof intentTopicSchema>;
+export declare const semanticSummarySchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const revokeReasonSchema: z.ZodEnum<["fulfilled", "user_requested", "issuer_invalidated", "other"]>;
+export type RevokeReason = z.infer<typeof revokeReasonSchema>;
+/** Canonical Hark intent object (CLAUDE.md section 9). */
+export declare const harkIntentSchema: z.ZodObject<{
+    id: z.ZodString;
+    publisherId: z.ZodString;
+    subjectRef: z.ZodString;
+    placementIds: z.ZodArray<z.ZodString, "many">;
+    topics: z.ZodArray<z.ZodObject<{
+        id: z.ZodEffects<z.ZodString, string, string>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        confidence?: number | undefined;
+    }, {
+        id: string;
+        confidence?: number | undefined;
+    }>, "many">;
+    semanticSummary: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    assurances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        provider: z.ZodString;
+        level: z.ZodOptional<z.ZodString>;
+        issuedAt: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }, {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }>, "many">>;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    revokedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    revokeReason: z.ZodOptional<z.ZodNullable<z.ZodEnum<["fulfilled", "user_requested", "issuer_invalidated", "other"]>>>;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: string;
+    id: string;
+    createdAt: string;
+    publisherId: string;
+    subjectRef: string;
+    placementIds: string[];
+    topics: {
+        id: string;
+        confidence?: number | undefined;
+    }[];
+    semanticSummary?: string | undefined;
+    assurances?: {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }[] | undefined;
+    revokedAt?: string | null | undefined;
+    revokeReason?: "fulfilled" | "user_requested" | "issuer_invalidated" | "other" | null | undefined;
+}, {
+    expiresAt: string;
+    id: string;
+    createdAt: string;
+    publisherId: string;
+    subjectRef: string;
+    placementIds: string[];
+    topics: {
+        id: string;
+        confidence?: number | undefined;
+    }[];
+    semanticSummary?: string | undefined;
+    assurances?: {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }[] | undefined;
+    revokedAt?: string | null | undefined;
+    revokeReason?: "fulfilled" | "user_requested" | "issuer_invalidated" | "other" | null | undefined;
+}>;
+export type HarkIntent = z.infer<typeof harkIntentSchema>;
+/** POST /v1/intents request body. */
+export declare const createIntentInputSchema: z.ZodObject<{
+    subjectRef: z.ZodString;
+    placementIds: z.ZodArray<z.ZodString, "many">;
+    topics: z.ZodArray<z.ZodObject<{
+        id: z.ZodEffects<z.ZodString, string, string>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        confidence?: number | undefined;
+    }, {
+        id: string;
+        confidence?: number | undefined;
+    }>, "many">;
+    semanticSummary: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    assurances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        provider: z.ZodString;
+        level: z.ZodOptional<z.ZodString>;
+        issuedAt: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }, {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }>, "many">>;
+    expiresInSeconds: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    subjectRef: string;
+    placementIds: string[];
+    topics: {
+        id: string;
+        confidence?: number | undefined;
+    }[];
+    expiresInSeconds: number;
+    semanticSummary?: string | undefined;
+    assurances?: {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }[] | undefined;
+}, {
+    subjectRef: string;
+    placementIds: string[];
+    topics: {
+        id: string;
+        confidence?: number | undefined;
+    }[];
+    semanticSummary?: string | undefined;
+    assurances?: {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }[] | undefined;
+    expiresInSeconds?: number | undefined;
+}>;
+export type CreateIntentInput = z.infer<typeof createIntentInputSchema>;
+/** PATCH /v1/intents/:intentId request body. */
+export declare const updateIntentInputSchema: z.ZodObject<{
+    placementIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    topics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodEffects<z.ZodString, string, string>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        confidence?: number | undefined;
+    }, {
+        id: string;
+        confidence?: number | undefined;
+    }>, "many">>;
+    semanticSummary: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+    assurances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        provider: z.ZodString;
+        level: z.ZodOptional<z.ZodString>;
+        issuedAt: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }, {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }>, "many">>;
+    expiresInSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    placementIds?: string[] | undefined;
+    topics?: {
+        id: string;
+        confidence?: number | undefined;
+    }[] | undefined;
+    semanticSummary?: string | null | undefined;
+    assurances?: {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }[] | undefined;
+    expiresInSeconds?: number | undefined;
+}, {
+    placementIds?: string[] | undefined;
+    topics?: {
+        id: string;
+        confidence?: number | undefined;
+    }[] | undefined;
+    semanticSummary?: string | null | undefined;
+    assurances?: {
+        type: string;
+        provider: string;
+        level?: string | undefined;
+        issuedAt?: string | undefined;
+        expiresAt?: string | undefined;
+    }[] | undefined;
+    expiresInSeconds?: number | undefined;
+}>;
+export type UpdateIntentInput = z.infer<typeof updateIntentInputSchema>;
+/** DELETE /v1/intents/:intentId request body. */
+export declare const revokeIntentInputSchema: z.ZodObject<{
+    reason: z.ZodDefault<z.ZodEnum<["fulfilled", "user_requested", "issuer_invalidated", "other"]>>;
+}, "strip", z.ZodTypeAny, {
+    reason: "fulfilled" | "user_requested" | "issuer_invalidated" | "other";
+}, {
+    reason?: "fulfilled" | "user_requested" | "issuer_invalidated" | "other" | undefined;
+}>;
+export type RevokeIntentInput = z.infer<typeof revokeIntentInputSchema>;
+//# sourceMappingURL=intent.d.ts.map

package/dist/schemas/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../src/schemas/intent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,iBAAiB;;;;;;;;;EAG5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,qBAAqB,2CAK9B,CAAC;AAEL,eAAO,MAAM,kBAAkB,2EAK7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAa3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,qCAAqC;AACrC,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,gDAAgD;AAChD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,iDAAiD;AACjD,eAAO,MAAM,uBAAuB;;;;;;EAElC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/schemas/intent.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { containsObviousPii } from "../pii.js";
+import { assuranceSchema } from "./assurance.js";
+import { INTENT_DEFAULT_TTL_SECONDS, INTENT_MAX_TTL_SECONDS, SEMANTIC_SUMMARY_MAX_LENGTH, } from "../constants.js";
+import { isValidTopicId } from "../taxonomy.js";
+export const intentTopicSchema = z.object({
+    id: z.string().refine(isValidTopicId, { message: "Unknown topic id" }),
+    confidence: z.number().min(0).max(1).optional(),
+});
+export const semanticSummarySchema = z
+    .string()
+    .max(SEMANTIC_SUMMARY_MAX_LENGTH)
+    .refine((value) => !containsObviousPii(value), {
+    message: "Semantic summary appears to contain PII (email or phone number)",
+});
+export const revokeReasonSchema = z.enum([
+    "fulfilled",
+    "user_requested",
+    "issuer_invalidated",
+    "other",
+]);
+/** Canonical Hark intent object (CLAUDE.md section 9). */
+export const harkIntentSchema = z.object({
+    id: z.string(),
+    publisherId: z.string(),
+    // Opaque, publisher-scoped reference. Never returned from advertiser-facing endpoints.
+    subjectRef: z.string(),
+    placementIds: z.array(z.string()),
+    topics: z.array(intentTopicSchema).min(1),
+    semanticSummary: semanticSummarySchema.optional(),
+    assurances: z.array(assuranceSchema).optional(),
+    createdAt: z.string().datetime(),
+    expiresAt: z.string().datetime(),
+    revokedAt: z.string().datetime().nullable().optional(),
+    revokeReason: revokeReasonSchema.nullable().optional(),
+});
+/** POST /v1/intents request body. */
+export const createIntentInputSchema = z.object({
+    subjectRef: z.string().min(1),
+    placementIds: z.array(z.string()).min(1),
+    topics: z.array(intentTopicSchema).min(1),
+    semanticSummary: semanticSummarySchema.optional(),
+    assurances: z.array(assuranceSchema).optional(),
+    expiresInSeconds: z
+        .number()
+        .int()
+        .positive()
+        .max(INTENT_MAX_TTL_SECONDS)
+        .default(INTENT_DEFAULT_TTL_SECONDS),
+});
+/** PATCH /v1/intents/:intentId request body. */
+export const updateIntentInputSchema = z.object({
+    placementIds: z.array(z.string()).min(1).optional(),
+    topics: z.array(intentTopicSchema).min(1).optional(),
+    semanticSummary: semanticSummarySchema.nullable().optional(),
+    assurances: z.array(assuranceSchema).optional(),
+    expiresInSeconds: z.number().int().positive().max(INTENT_MAX_TTL_SECONDS).optional(),
+});
+/** DELETE /v1/intents/:intentId request body. */
+export const revokeIntentInputSchema = z.object({
+    reason: revokeReasonSchema.default("other"),
+});
+//# sourceMappingURL=intent.js.map

package/dist/schemas/intent.js.map

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