@authorizedretailers/spec 0.1.1 → 0.2.0

package/dist/types.d.ts

@@ -1,85 +1,124 @@
-export declare const SPEC_VERSION: "authorized-retailers/0.1";
+export declare const SPEC_VERSION: "authorized-retailers/0.2";
 export type SpecVersion = typeof SPEC_VERSION;
-/** RFC 3339 UTC timestamp, e.g. "2026-09-23T00:00:00Z". */
+/** RFC 3339 UTC timestamp, e.g. "2026-09-28T00:00:00Z". */
 export type Timestamp = string;
-export interface Brand {
-    name: string;
-    domain: string;
-}
 export type MarketplaceChannelType = "amazon" | "walmart" | "ebay";
+/** Section 6: a marketplace seller, identified by the marketplace domain and seller ID. */
 export interface MarketplaceChannel {
     type: MarketplaceChannelType;
-    marketplace: string;
+    /** One of that type's marketplace domains, e.g. "amazon.com" (see MARKETPLACE_DOMAINS). */
+    domain: string;
     seller_id: string;
 }
 export interface WebChannel {
     type: "web";
     domain: string;
 }
-export interface PhysicalChannel {
-    type: "physical";
-    address: string;
-    country: string;
-}
-/** A channel an agent can see and match on (section 6). */
-export type VerifiableChannel = MarketplaceChannel | WebChannel;
-export type Channel = VerifiableChannel | PhysicalChannel;
+/** Section 6: every channel is identified by a domain. */
+export type Channel = MarketplaceChannel | WebChannel;
 export type ChannelType = Channel["type"];
 export interface Party {
     name: string;
     entity_id?: string;
 }
+/** Section 3.1: one product in a brand's catalog. Has a gtin, asins or both. */
+export interface Product {
+    id: string;
+    name: string;
+    product_line?: string;
+    attributes?: Record<string, string>;
+    gtin?: string;
+    asins?: string[];
+}
 export interface Scope {
-    /** ISO 3166-1 alpha-2 codes, or exactly ["*"]. */
-    territories: string[];
+    /** ISO 3166-1 alpha-2 codes, or exactly ["*"]. Optional: most channels take territory from their domain (section 6.2). */
+    territories?: string[];
     /** Named product lines, or exactly ["all"]. */
-    product_lines: string[];
+    product_lines?: string[];
+    /** Catalog product IDs. */
+    products?: string[];
+    exclude_product_lines?: string[];
+    exclude_products?: string[];
+}
+export interface Exclusions {
+    product_lines?: string[];
+    products?: string[];
 }
 export interface Authorization {
     id: string;
+    /** Section 10.3: random, replaced whenever the authorization's coverage shrinks. */
+    revocation_id: string;
     retailer: Party;
     channels: Channel[];
     scope: Scope;
     proposed_by?: Party | null;
-    expires: Timestamp;
+    /** Optional end date set by the brand (section 10). */
+    expires?: Timestamp;
 }
 export interface Signature {
     kid: string;
     /** Detached compact JWS: "<header>..<signature>". */
     jws: string;
 }
-export interface FullFile {
-    spec: SpecVersion;
-    form: "full";
-    brand: Brand;
-    issued: Timestamp;
-    expires: Timestamp;
-    authorizations: Authorization[];
-    signature?: Signature;
-}
+/** Section 5.1: the optional, unsigned file at /.well-known/authorized-retailers.json. */
 export interface PointerFile {
     spec: SpecVersion;
     form: "pointer";
-    brand: Brand;
+    brand: {
+        name: string;
+        domain: string;
+    };
+    verify_token: string;
+    /** Always an https://authorizedretailers.ai/ URL. */
     list: string;
 }
-export interface PrivateFile {
+/** The only file form in v0.2. */
+export type AuthorizedRetailersFile = PointerFile;
+export type FileForm = PointerFile["form"];
+interface ListBase {
     spec: SpecVersion;
-    form: "private";
-    brand: Brand;
-    verify: string;
+    brand: {
+        name: string;
+        domains: string[];
+    };
+    issued: Timestamp;
+    /** At most 15 minutes after issued (section 10.1). */
+    valid_until: Timestamp;
+    /** At most 24 hours after issued (section 10.2). */
+    stale_until: Timestamp;
+    signature: Signature;
+}
+/** Section 5.2: a brand's signed list, as published by the registry. */
+export interface PublicList extends ListBase {
+    public: true;
+    catalog?: Product[];
+    exclusions?: Exclusions;
+    authorizations: Authorization[];
 }
-export type AuthorizedRetailersFile = FullFile | PointerFile | PrivateFile;
-export type FileForm = AuthorizedRetailersFile["form"];
+/** Section 5.2: the signed response for a brand whose list is not public. */
+export interface NotPublicList extends ListBase {
+    public: false;
+}
+export type SignedList = PublicList | NotPublicList;
+/** Exactly one of gtin or asin. */
+export type ProductRef = {
+    gtin: string;
+} | {
+    asin: string;
+};
 export interface VerifyRequest {
     brand_domain: string;
-    channel: VerifiableChannel;
-    territory: string;
-    /** Defaults to "all". */
+    channel: Channel;
+    /** Defaults to the channel domain's country. Required for web stores on generic domains. */
+    territory?: string;
     product_line?: string;
+    product?: ProductRef;
+    /** ISO 8601 date or UTC date-time. Defaults to now. */
+    as_of?: string;
 }
-export type VerifyStatus = "authorized" | "unlisted" | "expired" | "brand_unverified" | "disputed";
-export type UnverifiedReason = "not_registered" | "domain_unlinked" | "verification_lapsed";
+export type VerifyStatus = "authorized" | "unlisted" | "expired" | "brand_not_registered" | "disputed";
+export type NotRegisteredReason = "not_registered" | "domain_unlinked" | "verification_lapsed";
+export type UnlistedReason = "territory_mismatch" | "product_excluded" | "product_not_in_scope" | "product_not_in_catalog";
 export interface Signal {
     type: string;
     observed: Timestamp;
@@ -89,28 +128,63 @@ export interface Signal {
 export interface Observation {
     last_seen: Timestamp;
 }
+/** Section 9: present when the request named a product. id and product_line only for public lists. */
+export interface ProductResult {
+    in_catalog: boolean;
+    id?: string;
+    product_line?: string;
+}
 interface VerifyResponseBase {
     checked: Timestamp;
-    /** At most 24 hours after `checked` (section 9). */
+    as_of?: Timestamp;
+    /** At most 15 minutes after `checked` (section 9). */
     valid_until: Timestamp;
+    /** At most 24 hours after `checked` (section 10.2). */
+    stale_until: Timestamp;
+    product?: ProductResult;
     /** Non-null only on `authorized` answers (section 7). */
     observed: Observation | null;
     signals: Signal[];
     signature: Signature;
 }
-export interface VerifyResponseWithAuthorization extends VerifyResponseBase {
-    status: "authorized" | "expired" | "disputed";
+export interface VerifyResponseAuthorized extends VerifyResponseBase {
+    status: "authorized";
+    authorization_id: string;
+    revocation_id: string;
+    expires?: Timestamp;
+}
+export interface VerifyResponseExpired extends VerifyResponseBase {
+    status: "expired";
     authorization_id: string;
     expires: Timestamp;
 }
+export interface VerifyResponseDisputed extends VerifyResponseBase {
+    status: "disputed";
+    authorization_id: string;
+    expires?: Timestamp;
+}
 export interface VerifyResponseUnlisted extends VerifyResponseBase {
     status: "unlisted";
+    reason?: UnlistedReason;
 }
-export interface VerifyResponseBrandUnverified extends VerifyResponseBase {
-    status: "brand_unverified";
-    reason?: UnverifiedReason;
+export interface VerifyResponseNotRegistered extends VerifyResponseBase {
+    status: "brand_not_registered";
+    reason?: NotRegisteredReason;
 }
-export type VerifyResponse = VerifyResponseWithAuthorization | VerifyResponseUnlisted | VerifyResponseBrandUnverified;
+export type VerifyResponse = VerifyResponseAuthorized | VerifyResponseExpired | VerifyResponseDisputed | VerifyResponseUnlisted | VerifyResponseNotRegistered;
 /** A verify response before the registry attaches its signature. */
 export type UnsignedVerifyResponse = VerifyResponse extends infer R ? R extends VerifyResponseBase ? Omit<R, "signature"> : never : never;
+/** Section 10.3: the signed feed of revocation IDs from the last 24 hours. */
+export interface RevocationFeed {
+    spec: SpecVersion;
+    feed: "revocations";
+    issued: Timestamp;
+    valid_until: Timestamp;
+    stale_until: Timestamp;
+    entries: {
+        revocation_id: string;
+        revoked: Timestamp;
+    }[];
+    signature: Signature;
+}
 export {};

package/dist/types.js

@@ -1,2 +1,2 @@
-// Types mirror schemas/*.json. The schemas are canonical; if the two disagree, the schema wins.
-export const SPEC_VERSION = "authorized-retailers/0.1";
+// Types mirror schemas/0.2/*.json. The schemas are canonical; if the two disagree, the schema wins.
+export const SPEC_VERSION = "authorized-retailers/0.2";

package/dist/validate.d.ts

@@ -1,8 +1,14 @@
-import type { AuthorizedRetailersFile, Channel, Scope, FullFile, PointerFile, PrivateFile, VerifyRequest, VerifyResponse } from "./types.js";
-export type ErrorCode = "schema" | "no_online_channel" | "invalid_timestamp" | "expires_not_after_issued" | "file_expiry_exceeds_max" | "authorization_expires_after_file" | "duplicate_authorization_id" | "valid_until_not_after_checked" | "valid_until_exceeds_max";
+import type { Channel, PointerFile, RevocationFeed, Scope, SignedList, VerifyRequest, VerifyResponse } from "./types.js";
+export type ErrorCode = "schema" | "form_not_supported" | "list_not_on_registry" | "brand_domain_mismatch" | "unknown_channel_type" | "marketplace_field_removed" | "marketplace_domain_mismatch" | "invalid_country" | "territory_mismatch" | "territories_required" | "territory_required" | "invalid_gtin" | "invalid_asin" | "product_without_identifier" | "duplicate_product_id" | "duplicate_identifier" | "unknown_product_line" | "unknown_product" | "invalid_timestamp" | "duplicate_authorization_id" | "valid_until_not_after_issued" | "valid_until_exceeds_max" | "stale_until_before_valid_until" | "stale_until_exceeds_max";
+export type WarningCode = "territory_differs_from_domain";
 export interface ValidationError {
     code: ErrorCode;
-    /** JSON Pointer into the instance, e.g. "/authorizations/0/expires". */
+    /** JSON Pointer into the instance, e.g. "/authorizations/0/channels/1". */
+    path: string;
+    message: string;
+}
+export interface ValidationWarning {
+    code: WarningCode;
     path: string;
     message: string;
 }
@@ -10,19 +16,27 @@ export type ValidationResult<T> = {
     valid: true;
     value: T;
     errors: [];
+    warnings: ValidationWarning[];
 } | {
     valid: false;
     errors: ValidationError[];
+    warnings: ValidationWarning[];
 };
-/** Validates an authorized-retailers.json file of any form. */
-export declare function validateFile(input: unknown): ValidationResult<AuthorizedRetailersFile>;
-export declare function validateFullFile(input: unknown): ValidationResult<FullFile>;
-export declare function validatePointerFile(input: unknown): ValidationResult<PointerFile>;
-export declare function validatePrivateFile(input: unknown): ValidationResult<PrivateFile>;
+/**
+ * Validates a pointer file (section 5.1). Pass the domain it was fetched from (the domain first
+ * asked for, before any redirects) to check that the pointer vouches for it.
+ */
+export declare function validateFile(input: unknown, fetchedFrom?: string): ValidationResult<PointerFile>;
+/** Validates a signed list or not-public response (section 5.2). Does not check the signature: see checkPublishedList. */
+export declare function validateList(input: unknown): ValidationResult<SignedList>;
 /** Validates a canonical verify request. Call normalizeVerifyRequest on raw agent input first. */
 export declare function validateVerifyRequest(input: unknown): ValidationResult<VerifyRequest>;
 export declare function validateVerifyResponse(input: unknown): ValidationResult<VerifyResponse>;
-/** Validates one authorization scope (§3), e.g. before a registry stores it. */
+/** Validates a revocation feed (section 10.3). Does not check the signature: see checkRevocationFeed. */
+export declare function validateRevocationFeed(input: unknown): ValidationResult<RevocationFeed>;
+/** Validates one authorization scope (section 3), e.g. before the registry stores it. */
 export declare function validateScope(input: unknown): ValidationResult<Scope>;
-/** Validates one channel identifier (§6), e.g. before a registry stores it. */
+/** Validates one channel identifier (section 6), e.g. before the registry stores it. */
 export declare function validateChannel(input: unknown): ValidationResult<Channel>;
+/** Validates one catalog product (section 3.1), e.g. a row from a brand's CSV import. */
+export declare function validateProduct(input: unknown): ValidationResult<import("./types.js").Product>;