@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.12

package/packages/agentsam-merch/src/derivatives.js

@@ -0,0 +1,112 @@
+import { evaluateManufacturingCompatibility } from "./compatibility.js";
+import { normalizeManufacturingProfile } from "./profile.js";
+
+export const DERIVATIVE_ROLE = Object.freeze({
+  ORIGINAL: "original/master",
+  MANUFACTURING: "manufacturing",
+  STOREFRONT: "storefront/gallery",
+  THUMBNAIL: "thumbnail",
+  SOCIAL: "social",
+  MOCKUP: "mockup",
+});
+
+export function planMediaDerivatives({
+  asset,
+  profile,
+  target = {},
+  storefrontFormat = "webp",
+  thumbnailFormat = "webp",
+  socialFormat = "jpg",
+  mockupFormat = "webp",
+} = {}) {
+  const normalizedProfile = normalizeManufacturingProfile(profile);
+  const compatibility = evaluateManufacturingCompatibility(asset, normalizedProfile, target);
+
+  return Object.freeze({
+    source: Object.freeze({
+      role: DERIVATIVE_ROLE.ORIGINAL,
+      preserve: true,
+      immutableAuthority: true,
+      format: asset?.format || null,
+    }),
+    manufacturing: Object.freeze({
+      role: DERIVATIVE_ROLE.MANUFACTURING,
+      preserve: true,
+      derivedFrom: DERIVATIVE_ROLE.ORIGINAL,
+      format: normalizedProfile.format,
+      profileId: normalizedProfile.id,
+      compatibility,
+      mustNotUseStorefrontDerivative: true,
+    }),
+    storefront: Object.freeze({
+      role: DERIVATIVE_ROLE.STOREFRONT,
+      preserve: false,
+      derivedFrom: DERIVATIVE_ROLE.ORIGINAL,
+      format: storefrontFormat,
+      optimizeFor: "delivery",
+    }),
+    thumbnail: Object.freeze({
+      role: DERIVATIVE_ROLE.THUMBNAIL,
+      preserve: false,
+      derivedFrom: DERIVATIVE_ROLE.ORIGINAL,
+      format: thumbnailFormat,
+      optimizeFor: "small-ui",
+    }),
+    social: Object.freeze({
+      role: DERIVATIVE_ROLE.SOCIAL,
+      preserve: false,
+      derivedFrom: DERIVATIVE_ROLE.ORIGINAL,
+      format: socialFormat,
+      optimizeFor: "social",
+    }),
+    mockup: Object.freeze({
+      role: DERIVATIVE_ROLE.MOCKUP,
+      preserve: false,
+      derivedFrom: DERIVATIVE_ROLE.ORIGINAL,
+      format: mockupFormat,
+      optimizeFor: "preview",
+    }),
+  });
+}
+
+export function buildMerchPlan({ design, products = [], registry }) {
+  if (!design?.asset) throw new TypeError("design.asset is required");
+  if (!registry?.get || !registry?.select) {
+    throw new TypeError("a manufacturing profile registry is required");
+  }
+
+  const targets = products.map((product) => {
+    const profile =
+      (product.profileId && registry.get(product.profileId)) ||
+      registry.select(product.profileContext || product);
+
+    if (!profile) {
+      return Object.freeze({
+        id: product.id,
+        name: product.name || product.id,
+        profileId: null,
+        status: "unsupported",
+        reason: "No manufacturing profile matched.",
+      });
+    }
+
+    const derivatives = planMediaDerivatives({
+      asset: design.asset,
+      profile,
+      target: product.target || product,
+    });
+
+    return Object.freeze({
+      ...product,
+      profileId: profile.id,
+      status: derivatives.manufacturing.compatibility.status,
+      derivatives,
+    });
+  });
+
+  return Object.freeze({
+    schemaVersion: "agentsam.merch-plan.v1",
+    design: Object.freeze({ ...design }),
+    targets: Object.freeze(targets),
+  });
+}

package/packages/agentsam-merch/src/index.d.ts

@@ -0,0 +1,316 @@
+export type MediaKind = "raster" | "vector" | "document" | "unknown";
+export type CompatibilityStatus =
+  | "ready"
+  | "ready_with_warning"
+  | "ready_with_transform"
+  | "prepared_for_digitization"
+  | "needs_variant"
+  | "unsupported";
+export type TransformPolicy = "auto" | "preserve";
+
+export interface ResolutionPolicy {
+  readyPpi: number | null;
+  minimumPpi: number | null;
+}
+
+export interface AutoNormalizePolicy {
+  trimAlpha: boolean;
+  colorSpace: boolean;
+  svgOptimize: boolean;
+  outlineText: boolean;
+}
+
+export interface VectorizationPolicy {
+  enabled: boolean;
+  preferredTracer: string | null;
+  maxAspectDrift: number;
+  minBoundaryIntegrity: number;
+  outputFormat: string | null;
+}
+
+export interface ManufacturingProfile {
+  schemaVersion?: "agentsam.manufacturing-profile.v1" | string;
+  $schema?: string;
+  id: string;
+  manufacturer: string;
+  process: string;
+  format?: string;
+  preferredFormat?: string;
+  colorSpace?: string | null;
+  colorMode?: string | null;
+  alpha?: boolean;
+  requireAlpha?: boolean;
+  ppi?: number | null;
+  resolution?: Partial<ResolutionPolicy> | ResolutionPolicy;
+  autoNormalize?: Partial<AutoNormalizePolicy> | AutoNormalizePolicy;
+  vectorization?: Partial<VectorizationPolicy> | VectorizationPolicy;
+  maxBytes?: number | null;
+  preferredPrintWidthIn?: number | null;
+  preferredPrintHeightIn?: number | null;
+  allowRaster?: boolean;
+  allowVector?: boolean;
+  allowGradients?: boolean;
+  requireClosedPaths?: boolean;
+  requireViewBox?: boolean;
+  outlineText?: boolean;
+  match?: Record<string, unknown> | null;
+  handoff?: { status?: string; reason?: string; [key: string]: unknown } | null;
+  source?: { kind?: string; verified?: boolean; [key: string]: unknown } | null;
+  [key: string]: unknown;
+}
+
+export interface SourceAssetDescriptor {
+  format?: string;
+  extension?: string;
+  mimeType?: string;
+  mediaKind?: MediaKind;
+  widthPx?: number;
+  heightPx?: number;
+  contentWidthPx?: number;
+  contentHeightPx?: number;
+  trimmedWidthPx?: number;
+  trimmedHeightPx?: number;
+  width?: number;
+  height?: number;
+  bytes?: number;
+  sizeBytes?: number;
+  colorSpace?: string;
+  colorMode?: string;
+  hasAlpha?: boolean;
+  transparentBorderDetected?: boolean;
+  isAlphaTrimmed?: boolean;
+  hasGradients?: boolean;
+  hasOpenPaths?: boolean;
+  hasLiveText?: boolean;
+  hasExplicitViewBox?: boolean;
+  [key: string]: unknown;
+}
+
+export interface ManufacturingTarget {
+  placementWidthIn?: number | null;
+  placementHeightIn?: number | null;
+  printWidthIn?: number | null;
+  printHeightIn?: number | null;
+  providerDpi?: number | null;
+  [key: string]: unknown;
+}
+
+export interface CompatibilityIssue {
+  status: CompatibilityStatus;
+  code: string;
+  message: string;
+  action: string | null;
+  meta?: Record<string, unknown> | null;
+}
+
+export interface EffectivePpiResult {
+  effectivePpi: number | null;
+  widthPpi: number | null;
+  heightPpi: number | null;
+  widthIn: number | null;
+  heightIn: number | null;
+  basis: "content_bounds" | "pixel_bounds" | null;
+}
+
+export interface ManufacturingCompatibility {
+  profileId: string | null;
+  manufacturer: string | null;
+  process: string | null;
+  status: CompatibilityStatus;
+  requirementsVerified: boolean;
+  productionReady: boolean;
+  transformReady: boolean;
+  effectivePpi: number | null;
+  resolution: {
+    band: "ready" | "warning" | "fail" | "unknown";
+    basis: "content_bounds" | "pixel_bounds" | null;
+    widthPpi: number | null;
+    heightPpi: number | null;
+    readyPpi: number | null;
+    minimumPpi: number | null;
+  };
+  target: {
+    format: string | null;
+    ppi: number | null;
+    printWidthIn: number | null;
+    printHeightIn: number | null;
+  };
+  issues: readonly CompatibilityIssue[];
+  actions: readonly string[];
+  handoff: ManufacturingProfile["handoff"];
+}
+
+export interface ManufacturingProfileRegistry {
+  register(profile: ManufacturingProfile, options?: { replace?: boolean }): Readonly<ManufacturingProfile>;
+  get(id: string): Readonly<ManufacturingProfile> | null;
+  list(filter?: { manufacturer?: string; process?: string }): Readonly<ManufacturingProfile>[];
+  select(context?: Record<string, unknown>): Readonly<ManufacturingProfile> | null;
+  unregister(id: string): boolean;
+}
+
+export const MANUFACTURING_PROFILE_SCHEMA: "agentsam.manufacturing-profile.v1";
+export const RASTER_FORMATS: readonly string[];
+export const VECTOR_FORMATS: readonly string[];
+export const DOCUMENT_FORMATS: readonly string[];
+export function normalizeFormat(value: unknown): string | null;
+export function mediaKindForFormat(value: unknown): MediaKind;
+export function normalizeResolutionPolicy(
+  input?: Partial<ResolutionPolicy>,
+  fallbackPpi?: number | null,
+): Readonly<ResolutionPolicy>;
+export function normalizeManufacturingProfile(input?: ManufacturingProfile): Readonly<ManufacturingProfile>;
+export function validateManufacturingProfile(input: ManufacturingProfile): {
+  ok: boolean;
+  errors: readonly string[];
+  profile: Readonly<ManufacturingProfile>;
+};
+export function createManufacturingProfileRegistry(
+  profiles?: ManufacturingProfile[],
+): ManufacturingProfileRegistry;
+
+export const COMPATIBILITY_STATUS: Readonly<{
+  READY: "ready";
+  READY_WITH_WARNING: "ready_with_warning";
+  READY_WITH_TRANSFORM: "ready_with_transform";
+  PREPARED_FOR_DIGITIZATION: "prepared_for_digitization";
+  NEEDS_VARIANT: "needs_variant";
+  UNSUPPORTED: "unsupported";
+}>;
+export function calculateEffectivePpi(
+  asset: SourceAssetDescriptor,
+  profile: ManufacturingProfile,
+  target?: ManufacturingTarget,
+): Readonly<EffectivePpiResult>;
+export function evaluateManufacturingCompatibility(
+  asset: SourceAssetDescriptor,
+  profile: ManufacturingProfile,
+  target?: ManufacturingTarget,
+): Readonly<ManufacturingCompatibility>;
+export function evaluateCompatibleProducts(
+  asset: SourceAssetDescriptor,
+  products: Record<string, unknown>[],
+  registry: ManufacturingProfileRegistry,
+): Readonly<Record<string, unknown>>[];
+
+export interface TransformOperation {
+  id: string;
+  automatic: boolean;
+  requires: readonly string[];
+  params: Readonly<Record<string, unknown>>;
+  issueCode?: string;
+  missingCapabilities?: readonly string[];
+  executable?: boolean;
+  note?: string;
+}
+export const TRANSFORM_OPERATION: Readonly<Record<string, string>>;
+export function planAutomaticTransforms(input: {
+  asset: SourceAssetDescriptor;
+  profile: ManufacturingProfile;
+  target?: ManufacturingTarget;
+  capabilities?: Record<string, boolean>;
+}): Readonly<{
+  compatibility: ManufacturingCompatibility;
+  operations: readonly TransformOperation[];
+  canExecuteAutomatically: boolean;
+  hasBlockingIssue: boolean;
+}>;
+export function verifyVectorizationResult(input: {
+  source: SourceAssetDescriptor;
+  result: SourceAssetDescriptor & { boundaryIntegrity?: number };
+  profile: ManufacturingProfile;
+}): Readonly<{
+  verified: boolean;
+  aspectOk: boolean;
+  boundaryOk: boolean;
+  aspectDrift: number | null;
+  boundaryIntegrity: number | null;
+  thresholds: Readonly<{ maxAspectDrift: number; minBoundaryIntegrity: number }>;
+  reason: string | null;
+}>;
+
+export const DERIVATIVE_ROLE: Readonly<{
+  ORIGINAL: "original/master";
+  MANUFACTURING: "manufacturing";
+  STOREFRONT: "storefront/gallery";
+  THUMBNAIL: "thumbnail";
+  SOCIAL: "social";
+  MOCKUP: "mockup";
+}>;
+export function planMediaDerivatives(input: {
+  asset: SourceAssetDescriptor;
+  profile: ManufacturingProfile;
+  target?: ManufacturingTarget;
+  storefrontFormat?: string;
+  thumbnailFormat?: string;
+  socialFormat?: string;
+  mockupFormat?: string;
+}): Readonly<Record<string, unknown>>;
+export function buildMerchPlan(input: {
+  design: { asset: SourceAssetDescriptor; [key: string]: unknown };
+  products?: Record<string, unknown>[];
+  registry: ManufacturingProfileRegistry;
+}): Readonly<Record<string, unknown>>;
+
+export type CollectionCandidateState =
+  | "concept"
+  | "approved-art"
+  | "production-ready"
+  | "sample-ordered"
+  | "sample-approved"
+  | "published"
+  | "retired";
+export interface CollectionCandidate {
+  id: string;
+  designId: string;
+  collectionPath: readonly string[];
+  state: CollectionCandidateState;
+  products: readonly Record<string, unknown>[];
+  approvals: Readonly<{ artwork: boolean; wording: boolean; palette: boolean; visualIdentity: boolean }>;
+  metadata: Readonly<Record<string, unknown>>;
+}
+export const COLLECTION_CANDIDATE_STATE: Readonly<Record<string, CollectionCandidateState>>;
+export function createCollectionCandidate(
+  input: Partial<CollectionCandidate> & Pick<CollectionCandidate, "id" | "designId">,
+): Readonly<CollectionCandidate>;
+export function canTransitionCollectionCandidate(from: CollectionCandidateState, to: CollectionCandidateState): boolean;
+export function transitionCollectionCandidate(
+  candidate: CollectionCandidate,
+  nextState: CollectionCandidateState,
+): Readonly<CollectionCandidate>;
+export function approvalsComplete(candidate: CollectionCandidate): boolean;
+
+export interface ProductConceptTarget {
+  provider: string;
+  profileId: string;
+  priority?: number;
+  enabled?: boolean;
+  adapter?: string;
+  metadata?: Record<string, unknown>;
+}
+export interface ProductConcept {
+  id: string;
+  label?: string;
+  category?: string;
+  targets: ProductConceptTarget[];
+  [key: string]: unknown;
+}
+export function normalizeProductConcept(input: ProductConcept): Readonly<ProductConcept>;
+export function createProductConceptRegistry(initial?: ProductConcept[]): Readonly<{
+  register(input: ProductConcept, options?: { replace?: boolean }): Readonly<ProductConcept>;
+  get(id: string): Readonly<ProductConcept> | null;
+  list(): Readonly<ProductConcept>[];
+}>;
+export function resolveProductConceptTarget(
+  concept: ProductConcept,
+  input: {
+    profileRegistry: ManufacturingProfileRegistry;
+    availableProviders?: string[];
+    preferredProvider?: string | null;
+  },
+): Readonly<Record<string, unknown>>;
+
+export function completefulProfileContext(
+  product?: Record<string, unknown>,
+  location?: Record<string, unknown>,
+): Readonly<Record<string, unknown>>;
+export function completefulTarget(location?: Record<string, unknown>): Readonly<ManufacturingTarget>;

package/packages/agentsam-merch/src/index.js

@@ -0,0 +1,46 @@
+export {
+  MANUFACTURING_PROFILE_SCHEMA,
+  RASTER_FORMATS,
+  VECTOR_FORMATS,
+  DOCUMENT_FORMATS,
+  mediaKindForFormat,
+  normalizeFormat,
+  normalizeManufacturingProfile,
+  normalizeResolutionPolicy,
+  validateManufacturingProfile,
+} from "./profile.js";
+export { createManufacturingProfileRegistry } from "./profile-registry.js";
+export {
+  COMPATIBILITY_STATUS,
+  calculateEffectivePpi,
+  evaluateManufacturingCompatibility,
+  evaluateCompatibleProducts,
+} from "./compatibility.js";
+export {
+  DERIVATIVE_ROLE,
+  planMediaDerivatives,
+  buildMerchPlan,
+} from "./derivatives.js";
+export {
+  COLLECTION_CANDIDATE_STATE,
+  approvalsComplete,
+  canTransitionCollectionCandidate,
+  createCollectionCandidate,
+  transitionCollectionCandidate,
+} from "./collection-lab.js";
+export {
+  completefulProfileContext,
+  completefulTarget,
+} from "./adapters-completeful.js";
+
+export {
+  TRANSFORM_OPERATION,
+  planAutomaticTransforms,
+  verifyVectorizationResult,
+} from "./transforms.js";
+
+export {
+  createProductConceptRegistry,
+  normalizeProductConcept,
+  resolveProductConceptTarget,
+} from "./product-concepts.js";

package/packages/agentsam-merch/src/node/index.d.ts

@@ -0,0 +1,58 @@
+import type { SourceAssetDescriptor, TransformOperation } from "../index.js";
+
+export interface NodeTransformCapabilities {
+  raster_normalizer: boolean;
+  format_converter: boolean;
+  vector_rasterizer: boolean;
+  vector_tracer: boolean;
+  svg_normalizer: boolean;
+  vector_normalizer: boolean;
+  text_outliner: boolean;
+  tools: Readonly<Record<string, boolean>>;
+}
+
+export function inspectRaster(
+  input: Buffer | Uint8Array | string,
+  options?: { sharp?: unknown },
+): Promise<Readonly<SourceAssetDescriptor>>;
+
+export function normalizeRaster(
+  input: Buffer | Uint8Array | string,
+  options?: {
+    operations?: readonly (string | TransformOperation)[];
+    format?: string;
+    sharp?: unknown;
+  },
+): Promise<Readonly<{
+  buffer: Buffer;
+  info: Readonly<Record<string, unknown>>;
+  descriptor: Readonly<SourceAssetDescriptor>;
+  operations: readonly string[];
+}>>;
+
+export function detectNodeTransformCapabilities(): Promise<Readonly<NodeTransformCapabilities>>;
+
+export function traceRasterToSvg(
+  input: Buffer | Uint8Array,
+  options?: {
+    tracer?: "auto" | "potrace" | "vtracer";
+    threshold?: number;
+    turdSize?: number;
+    sharp?: unknown;
+  },
+): Promise<Readonly<{
+  svg: string;
+  tracer: string;
+  descriptor: Readonly<SourceAssetDescriptor & { boundaryIntegrity: number }>;
+  metrics: Readonly<{ boundaryIntegrity: number; width: number; height: number }>;
+}>>;
+
+export function normalizeSvgWithSvgo(
+  svg: string,
+  options?: { multipass?: boolean },
+): Promise<Readonly<{
+  svg: string;
+  hasExplicitViewBox: boolean;
+  hasLiveText: boolean;
+  note: string;
+}>>;

package/packages/agentsam-merch/src/node/index.js

@@ -0,0 +1,6 @@
+export { inspectRaster, normalizeRaster } from "./raster.js";
+export {
+  detectNodeTransformCapabilities,
+  normalizeSvgWithSvgo,
+  traceRasterToSvg,
+} from "./vector.js";

package/packages/agentsam-merch/src/node/raster.js

@@ -0,0 +1,142 @@
+async function loadSharp(injected) {
+  if (injected) return injected;
+  try {
+    const mod = await import("sharp");
+    return mod.default || mod;
+  } catch (error) {
+    const wrapped = new Error(
+      "Raster normalization requires the optional 'sharp' runtime dependency.",
+    );
+    wrapped.code = "sharp_unavailable";
+    wrapped.cause = error;
+    throw wrapped;
+  }
+}
+
+function hasOperation(operations, id) {
+  return (operations || []).some((operation) =>
+    typeof operation === "string" ? operation === id : operation?.id === id,
+  );
+}
+
+function operation(operations, id) {
+  return (operations || []).find((item) =>
+    typeof item === "string" ? item === id : item?.id === id,
+  );
+}
+
+export async function inspectRaster(input, { sharp: injectedSharp } = {}) {
+  const sharp = await loadSharp(injectedSharp);
+  const image = sharp(input, { failOn: "warning" }).rotate();
+  const metadata = await image.metadata();
+
+  const descriptor = {
+    format: metadata.format || null,
+    mediaKind: "raster",
+    widthPx: metadata.width || null,
+    heightPx: metadata.height || null,
+    colorSpace: metadata.space || null,
+    hasAlpha: metadata.hasAlpha ?? null,
+    channels: metadata.channels || null,
+    density: metadata.density || null,
+  };
+
+  if (!metadata.hasAlpha) {
+    return Object.freeze({
+      ...descriptor,
+      contentWidthPx: metadata.width || null,
+      contentHeightPx: metadata.height || null,
+      transparentBorderDetected: false,
+      isAlphaTrimmed: true,
+    });
+  }
+
+  try {
+    const { info } = await sharp(input, { failOn: "warning" })
+      .rotate()
+      .trim({ background: { r: 0, g: 0, b: 0, alpha: 0 } })
+      .png()
+      .toBuffer({ resolveWithObject: true });
+
+    const trimmed =
+      Boolean(metadata.width && info.width && info.width < metadata.width) ||
+      Boolean(metadata.height && info.height && info.height < metadata.height);
+
+    return Object.freeze({
+      ...descriptor,
+      contentWidthPx: info.width || metadata.width || null,
+      contentHeightPx: info.height || metadata.height || null,
+      transparentBorderDetected: trimmed,
+      isAlphaTrimmed: !trimmed,
+    });
+  } catch {
+    return Object.freeze({
+      ...descriptor,
+      contentWidthPx: metadata.width || null,
+      contentHeightPx: metadata.height || null,
+      transparentBorderDetected: null,
+      isAlphaTrimmed: false,
+    });
+  }
+}
+
+export async function normalizeRaster(
+  input,
+  {
+    operations = [],
+    format = "png",
+    sharp: injectedSharp,
+  } = {},
+) {
+  const sharp = await loadSharp(injectedSharp);
+  let image = sharp(input, { failOn: "warning" }).rotate();
+
+  if (hasOperation(operations, "trim_alpha")) {
+    image = image.trim({ background: { r: 0, g: 0, b: 0, alpha: 0 } });
+  }
+
+  const colorOperation = operation(operations, "normalize_color_space");
+  const requestedColorSpace =
+    typeof colorOperation === "object"
+      ? colorOperation.params?.colorSpace || "srgb"
+      : "srgb";
+  if (colorOperation) {
+    image = image.toColourspace(requestedColorSpace);
+    if (typeof image.withIccProfile === "function") {
+      image = image.withIccProfile(requestedColorSpace);
+    } else {
+      image = image.withMetadata();
+    }
+  }
+
+  const target = String(format || "png").toLowerCase();
+  if (target === "png") {
+    image = image.png({
+      compressionLevel: 9,
+      adaptiveFiltering: true,
+      palette: false,
+    });
+  } else if (target === "jpg" || target === "jpeg") {
+    image = image.jpeg({ quality: 95, chromaSubsampling: "4:4:4" });
+  } else if (target === "webp") {
+    image = image.webp({ quality: 92, smartSubsample: true });
+  } else if (target === "tiff") {
+    image = image.tiff({ compression: "lzw" });
+  } else {
+    const error = new Error(`Unsupported raster normalization output: ${target}`);
+    error.code = "unsupported_raster_output";
+    throw error;
+  }
+
+  const { data, info } = await image.toBuffer({ resolveWithObject: true });
+  const descriptor = await inspectRaster(data, { sharp });
+
+  return Object.freeze({
+    buffer: data,
+    info: Object.freeze({ ...info }),
+    descriptor,
+    operations: Object.freeze(
+      operations.map((item) => (typeof item === "string" ? item : item.id)),
+    ),
+  });
+}