@instruments/materialgraph 2.3.0 → 3.0.1

package/catalog-client.d.ts

@@ -1,43 +0,0 @@
-import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogDocumentAccessResult, CatalogPageRepresentationReadResult, CatalogReferenceBatchResponse } from "./catalog-types.js";
-import type { HttpTransport } from "./http-transport.js";
-import type { VariantId } from "./identifiers.js";
-import type { ResolveVariantInput, ResolveVariantOutput } from "./resolve-variant-types.js";
-/** Catalog publication operations inherited by the public SDK client. */
-export declare class CatalogClient {
-    #private;
-    protected constructor(transport: HttpTransport);
-    /**
-     * THE QUESTION: "what does this brand page or code resolve to in the
-     * graph?" Give `input.url` alone, or `input.code` with `input.brandId` (from
-     * {@link CatalogClient.brands} - inherited by {@link MaterialGraphClient})
-     * when there is no page to read.
-     *
-     * Exact and scoreless: a sibling colorway, a similar image or a brand match
-     * alone never identifies a variant. Read `outcome` - `identified` names
-     * an exact stored variant, `placed` an exact brand with no variant match,
-     * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
-     * never a guess. The submitted URL is never persisted.
-     */
-    resolveVariant(input: ResolveVariantInput, signal?: AbortSignal): Promise<ResolveVariantOutput>;
-    /**
-     * Read exact, verified brand-publication page relationships for variants.
-     * Missing evidence stays explicit; this operation never guesses a page from
-     * a generic PDF.
-     */
-    catalogReferencesForVariants(input: {
-        variantIds: VariantId[];
-    }, signal?: AbortSignal): Promise<CatalogReferenceBatchResponse>;
-    /** List immutable catalog documents retained from verified source material. */
-    catalogs(signal?: AbortSignal): Promise<CatalogDocumentList>;
-    /** List stable one-based page identities and their representation status. */
-    catalogPages(catalogId: string, options?: {
-        limit?: number;
-        offset?: number;
-    }, signal?: AbortSignal): Promise<CatalogPageListResult>;
-    /** Read a retained page representation or its exact missing-artifact receipt. */
-    catalogPageRepresentation(pageId: string, signal?: AbortSignal): Promise<CatalogPageRepresentationReadResult>;
-    /** Read every verified product/page reference for one retained catalog. */
-    catalogReferences(catalogId: string, signal?: AbortSignal): Promise<CatalogProductReferenceReadResult>;
-    /** Resolve browser-safe access to one immutable catalog document. */
-    catalogDocumentAccess(documentId: string, signal?: AbortSignal): Promise<CatalogDocumentAccessResult>;
-}

package/catalog-client.js

@@ -1,51 +0,0 @@
-import { resolveOperation } from "./operations.js";
-/** Catalog publication operations inherited by the public SDK client. */
-export class CatalogClient {
-    #transport;
-    constructor(transport) {
-        this.#transport = transport;
-    }
-    /**
-     * THE QUESTION: "what does this brand page or code resolve to in the
-     * graph?" Give `input.url` alone, or `input.code` with `input.brandId` (from
-     * {@link CatalogClient.brands} - inherited by {@link MaterialGraphClient})
-     * when there is no page to read.
-     *
-     * Exact and scoreless: a sibling colorway, a similar image or a brand match
-     * alone never identifies a variant. Read `outcome` - `identified` names
-     * an exact stored variant, `placed` an exact brand with no variant match,
-     * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
-     * never a guess. The submitted URL is never persisted.
-     */
-    async resolveVariant(input, signal) {
-        return await this.#transport.requestJson(resolveOperation("resolve_variant"), { body: input, signal });
-    }
-    /**
-     * Read exact, verified brand-publication page relationships for variants.
-     * Missing evidence stays explicit; this operation never guesses a page from
-     * a generic PDF.
-     */
-    async catalogReferencesForVariants(input, signal) {
-        return await this.#transport.requestJson(resolveOperation("get_catalog_references_batch"), { body: input, signal });
-    }
-    /** List immutable catalog documents retained from verified source material. */
-    async catalogs(signal) {
-        return await this.#transport.requestJson(resolveOperation("list_catalog_documents"), { signal });
-    }
-    /** List stable one-based page identities and their representation status. */
-    async catalogPages(catalogId, options = {}, signal) {
-        return await this.#transport.requestJson(resolveOperation("list_catalog_pages"), { pathParams: { catalogId }, query: options, signal });
-    }
-    /** Read a retained page representation or its exact missing-artifact receipt. */
-    async catalogPageRepresentation(pageId, signal) {
-        return await this.#transport.requestJson(resolveOperation("get_catalog_page_representation"), { pathParams: { pageId }, signal });
-    }
-    /** Read every verified product/page reference for one retained catalog. */
-    async catalogReferences(catalogId, signal) {
-        return await this.#transport.requestJson(resolveOperation("list_catalog_product_references"), { pathParams: { catalogId }, signal });
-    }
-    /** Resolve browser-safe access to one immutable catalog document. */
-    async catalogDocumentAccess(documentId, signal) {
-        return await this.#transport.requestJson(resolveOperation("get_catalog_document_access"), { pathParams: { documentId }, signal });
-    }
-}

package/catalog-types.d.ts

@@ -1,373 +0,0 @@
-/** A verified product location in a specific immutable brand publication. */
-export type CatalogReference = {
-    anchor: {
-        coordinateSpace: "normalized_0_1000";
-        /** Page carrying the printed code; defaults to page.documentPage. Do not draw it on another page. */
-        documentPage?: number;
-        height: number;
-        kind: "printed_code";
-        width: number;
-        x: number;
-        y: number;
-    };
-    productRegion?: {
-        coordinateSpace: "normalized_0_1000";
-        height: number;
-        kind: "product_region";
-        review: {
-            approvedBy: string;
-            confidence: {
-                evidenceBasis: "human_visual_review" | "model_assisted_visual_review";
-                level: "reviewed";
-            };
-            method: "human" | "model_assisted";
-            model?: string;
-            reviewedAt: string;
-        };
-        width: number;
-        x: number;
-        y: number;
-    };
-    variantId: string;
-    brand: {
-        id: string;
-        name: string;
-    };
-    catalog: {
-        id: string;
-        title: string;
-    };
-    edition: {
-        id: string;
-        label: string;
-        title?: string;
-    };
-    document: {
-        id: string;
-        mediaType: "application/pdf";
-    };
-    page: {
-        documentPage: number;
-        printedPageLabel?: string;
-        pageCount?: number;
-    };
-    source: {
-        brandItemCode: string;
-    };
-    status: "verified";
-    isPrimary: boolean;
-};
-/**
- * Why a known variant has no verified reference. None of these says the
- * product is missing from the printed book; nobody records how many of a
- * brand's products a publication contains.
- */
-export type CatalogReferenceAbsenceReason = 
-/**
- * The registry retains no publication for the variant's brand. It says
- * nothing about whether the brand publishes one.
- */
-"no_publication_on_record"
-/** The edition is known but its document is not retained. */
- | "publication_source_unavailable"
-/** The document is retained but no page has been reviewed. */
- | "publication_not_reviewed"
-/** Pages were reviewed and this product is not among the references yet. */
- | "product_not_yet_referenced";
-/** The brand publication a `no_verified_reference` result was judged against. */
-export type CatalogReferencePublication = {
-    brand: {
-        id: string;
-        name: string;
-    };
-    catalog: {
-        id: string;
-        title: string;
-    };
-    /** Null when the edition's document is not retained. */
-    documentId: string | null;
-    edition: {
-        id: string;
-        label: string;
-        title?: string;
-    };
-    /** Reviewed references the publication holds; present only when its pages were reviewed. */
-    referencedProductCount?: number;
-};
-export type CatalogReferenceResult = {
-    variantId: string;
-    status: "verified";
-    reference: CatalogReference;
-} | {
-    variantId: string;
-    status: "no_verified_reference";
-    reason: CatalogReferenceAbsenceReason;
-    /** Absent only when `reason` is `no_publication_on_record`. */
-    publication?: CatalogReferencePublication;
-} | {
-    variantId: string;
-    status: "unresolved_variant";
-} | {
-    variantId: string;
-    status: "unavailable";
-} | {
-    variantId: string;
-    status: "upstream_failure";
-};
-export type CatalogReferenceBatchResponse = {
-    results: CatalogReferenceResult[];
-    coverage: {
-        requested: number;
-        verified: number;
-        noVerifiedReference: number;
-        unresolvedVariant: number;
-        unavailable: number;
-        upstreamFailure: number;
-    };
-};
-export type CatalogDocumentAccess = {
-    documentId: string;
-    contentType: "application/pdf";
-    readerUrl: string;
-    originalUrl: string;
-    byteRanges: "supported" | "unknown";
-};
-export type CatalogDocumentAccessResult = {
-    documentId: string;
-    status: "available";
-    access: CatalogDocumentAccess;
-} | {
-    documentId: string;
-    status: "unresolved_document";
-} | {
-    documentId: string;
-    status: "unavailable";
-} | {
-    documentId: string;
-    status: "forbidden";
-} | {
-    documentId: string;
-    status: "upstream_failure";
-};
-export type CatalogDocument = {
-    availability: "available";
-    brand: {
-        id: string;
-        name: string;
-    };
-    document: {
-        contentScope: "full_document" | "cover_only";
-        id: string;
-        mediaType: "application/pdf";
-        pageCount: number;
-    };
-    edition: CatalogEdition;
-    id: string;
-    kind: "document";
-    productStatus: "partial" | "not_processed";
-    receipt: CatalogAvailableReceipt;
-    title: string;
-};
-export type CatalogEdition = {
-    id: string;
-    label: string;
-    title: string;
-};
-export type CatalogAvailableReceipt = {
-    extraction: {
-        references: number;
-        status: "partial" | "not_processed";
-    };
-    failures: CatalogFailureReceipt[];
-    pages: {
-        documentPositionBase: 1;
-        pageCount: number;
-    };
-    render: {
-        failedPages: {
-            documentPage: number;
-            reason: string;
-        }[];
-        renderedPages: number;
-        status: "complete" | "partial" | "not_recorded";
-    };
-    source: {
-        checksum: {
-            algorithm: "sha256";
-            value: string;
-        };
-        valueSource: "brand_supplied";
-        retainedUrl: string;
-        status: "retained";
-    };
-};
-export type CatalogFailureReceipt = {
-    count: number;
-    reason: string;
-    stage: "source" | "render" | "extraction";
-};
-export type UnavailableCatalogDocument = {
-    availability: "source_unavailable";
-    brand: {
-        id: string;
-        name: string;
-    };
-    document: null;
-    edition: CatalogEdition;
-    id: string;
-    kind: "document";
-    productStatus: "not_processed";
-    receipt: {
-        extraction: {
-            references: 0;
-            status: "blocked_source_unavailable";
-        };
-        failures: CatalogFailureReceipt[];
-        pages: {
-            documentPositionBase: 1;
-            pageCount: null;
-        };
-        render: {
-            failedPages: never[];
-            renderedPages: 0;
-            status: "blocked_source_unavailable";
-        };
-        source: {
-            reason: "retained_source_not_found";
-            status: "unavailable";
-        };
-    };
-    title: string;
-};
-export type CatalogPublication = CatalogDocument | UnavailableCatalogDocument;
-export type CatalogDocumentList = {
-    catalogs: CatalogPublication[];
-    source: "verified-source-material-registry";
-};
-export type CatalogProductReferenceList = {
-    catalog: CatalogDocument;
-    coverage: {
-        documentPages: {
-            total: number;
-            withVerifiedReferences: number;
-        };
-        pagesWithReferences: number;
-        precision: {
-            reason: "labeled_denominator_not_recorded";
-            status: "not_measured";
-        };
-        productCoverage: {
-            reason: "source_product_denominator_not_recorded";
-            status: "not_measured";
-        };
-        references: number;
-        unmatched: {
-            reasons: "unmatched_source_products_not_recorded"[];
-            status: "not_measured";
-        };
-    };
-    references: CatalogReference[];
-    source: "verified-source-material-registry";
-    status: "available";
-};
-export type CatalogProductReferenceUnavailable = {
-    catalog: UnavailableCatalogDocument;
-    reason: "retained_source_not_found";
-    status: "source_unavailable";
-};
-export type CatalogProductReferenceReadResult = CatalogProductReferenceList | CatalogProductReferenceUnavailable;
-export type CatalogPageRequiredArtifact = {
-    mediaType: "image/webp";
-    version: "catalog-page-webp-v1";
-};
-export type CatalogPageAvailableArtifact = {
-    bucket: "materialgraph";
-    key: string;
-    url: string;
-    mediaType: CatalogPageRequiredArtifact["mediaType"];
-};
-export type CatalogPage = {
-    catalogId: string;
-    documentId: string;
-    editionId: string;
-    id: string;
-    original: {
-        documentId: string;
-        documentPage: number;
-    };
-    page: {
-        documentPage: number;
-        printedPageLabel?: string;
-    };
-    representation: {
-        artifact: CatalogPageAvailableArtifact;
-        status: "available";
-    };
-} | {
-    catalogId: string;
-    documentId: string;
-    editionId: string;
-    id: string;
-    original: {
-        documentId: string;
-        documentPage: number;
-    };
-    page: {
-        documentPage: number;
-        printedPageLabel?: string;
-    };
-    representation: {
-        requiredArtifact: CatalogPageRequiredArtifact;
-        reason: "retained_representation_not_found";
-        status: "unavailable";
-    };
-};
-type CatalogPageAvailable = Extract<CatalogPage, {
-    representation: {
-        status: "available";
-    };
-}>;
-type CatalogPageUnavailable = Extract<CatalogPage, {
-    representation: {
-        status: "unavailable";
-    };
-}>;
-export type CatalogPageListResult = {
-    catalog: CatalogDocument;
-    pages: CatalogPage[];
-    pagination: {
-        count: number;
-        hasMore: boolean;
-        limit: number;
-        offset: number;
-        total: number;
-    };
-    representationCoverage: {
-        available: number;
-        failuresByReason: {
-            count: number;
-            reason: "retained_representation_not_found";
-        }[];
-        total: number;
-        unavailable: number;
-    };
-    status: "available";
-} | {
-    catalog: UnavailableCatalogDocument;
-    reason: "retained_source_not_found";
-    status: "source_unavailable";
-};
-export type CatalogPageRepresentationReadResult = {
-    artifact: CatalogPageAvailableArtifact;
-    page: CatalogPageAvailable;
-    status: "available";
-} | {
-    requiredArtifact: CatalogPageRequiredArtifact;
-    page: CatalogPageUnavailable;
-    reason: "retained_representation_not_found";
-    status: "unavailable";
-} | {
-    pageId: string;
-    status: "unresolved_page";
-};
-export {};

package/catalog-types.js

@@ -1 +0,0 @@
-export {};