@plasius/asset-sources 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,216 @@
+declare const FEATURE_FLAGS: Readonly<{
+    readonly parent: "asset.pipeline.unified-ai-assets.enabled";
+    readonly externalHarvest: "asset.pipeline.external-model-harvest.enabled";
+    readonly polyHaven: "asset.pipeline.provider.polyhaven.enabled";
+    readonly kenney: "asset.pipeline.provider.kenney.enabled";
+    readonly smithsonian: "asset.pipeline.provider.smithsonian.enabled";
+    readonly nasa: "asset.pipeline.provider.nasa.enabled";
+    readonly sketchfab: "asset.pipeline.provider.sketchfab.enabled";
+}>;
+declare const CAPABILITIES: Readonly<{
+    readonly sourceManage: "asset.source.manage";
+    readonly catalogReview: "asset.catalog.review";
+    readonly catalogRequest: "asset.catalog.request";
+}>;
+type ProviderId = string & {
+    readonly __providerId: unique symbol;
+};
+type AssetIdentifier = string & {
+    readonly __assetIdentifier: unique symbol;
+};
+type Revision = number & {
+    readonly __revision: unique symbol;
+};
+type ProviderOperation = "search" | "resolveMetadata" | "requestDownload" | "download";
+type SupportedFormat = "glb" | "gltf" | "fbx" | "obj" | "blend" | "zip" | "unknown";
+type SourceReviewState = "pending" | "approved" | "rejected";
+type RightsEvidenceState = "approved" | "unknown" | "changed";
+type RightsPolicyState = "commercial-redistribution" | "commercial-with-attribution" | "not-approved";
+interface ProviderSourceDescriptor {
+    readonly providerId: ProviderId;
+    readonly displayName: string;
+    readonly enabled: boolean;
+    readonly featureFlag: string;
+    readonly parentFeatureFlag: typeof FEATURE_FLAGS.parent;
+    readonly requiredCapabilities: readonly string[];
+    readonly operationalGates: readonly string[];
+    readonly sourceReview: SourceReviewState;
+    readonly rightsPolicy: RightsPolicyState;
+    readonly supportedFormats: readonly SupportedFormat[];
+}
+interface SearchRequest {
+    readonly providerId: ProviderId;
+    readonly query: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+interface ResolveMetadataRequest {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+}
+interface RequestDownloadRequest {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly idempotencyKey: string;
+    readonly expectedRevision?: Revision;
+}
+interface DownloadRequest {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly acquisitionId: string;
+}
+interface RightsEvidence {
+    readonly state: RightsEvidenceState;
+    readonly policy: RightsPolicyState;
+    readonly evidenceRevision: Revision;
+    readonly attributionRequired: boolean;
+}
+interface ProviderAssetCandidate {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly title: string;
+    readonly description: string;
+    readonly sourcePage: string;
+    readonly rights: RightsEvidence;
+    readonly supportedFormats: readonly SupportedFormat[];
+    readonly revision: Revision;
+    readonly disposition: "eligible" | "quarantined";
+}
+interface ProviderAssetMetadata extends ProviderAssetCandidate {
+    readonly creator?: string;
+    readonly attributionText?: string;
+}
+interface CredentialRequest {
+    readonly providerId: ProviderId;
+    readonly operation: ProviderOperation;
+}
+interface ProviderCredential {
+    readonly kind: "oauth" | "api-key" | "none";
+    readonly value: string;
+}
+interface CredentialProvider {
+    getCredential(request: CredentialRequest): Promise<ProviderCredential | null>;
+}
+interface ProviderTransportRequest {
+    readonly providerId: ProviderId;
+    readonly operation: "search" | "resolveMetadata";
+    readonly assetId?: AssetIdentifier;
+    readonly query?: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+interface ProviderTransport {
+    execute(request: ProviderTransportRequest, credential: ProviderCredential | null): Promise<unknown>;
+}
+interface ProviderPayloadNormalizer {
+    normalizeSearch(payload: unknown): readonly ProviderAssetCandidate[];
+    normalizeMetadata(payload: unknown): ProviderAssetMetadata;
+}
+interface AcquisitionRequest {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly idempotencyKey: string;
+    readonly expectedRevision?: Revision;
+}
+interface AcquisitionReceipt {
+    readonly acquisitionId: string;
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly revision: Revision;
+    readonly status: "accepted" | "unavailable" | "quarantined";
+}
+interface AcquiredContent {
+    readonly acquisitionId: string;
+    readonly mediaType: string;
+    readonly byteLength: number;
+    readonly checksumSha256: string;
+}
+interface AcquisitionPort {
+    requestDownload(request: AcquisitionRequest): Promise<AcquisitionReceipt>;
+    download(request: DownloadRequest): Promise<AcquiredContent>;
+}
+interface PrivateStagingRef {
+    readonly stagingId: string;
+    readonly mediaType: string;
+    readonly byteLength: number;
+    readonly checksumSha256: string;
+    readonly expiresAt: string;
+}
+interface PrivateStagingPort {
+    stage(content: AcquiredContent): Promise<PrivateStagingRef>;
+}
+interface Checkpoint {
+    readonly idempotencyKey: string;
+    readonly receipt: AcquisitionReceipt;
+}
+interface CheckpointPort {
+    get(idempotencyKey: string): Promise<Checkpoint | null>;
+    put(checkpoint: Checkpoint): Promise<void>;
+}
+interface ProviderConnector {
+    readonly descriptor: ProviderSourceDescriptor;
+    search(request: SearchRequest): Promise<readonly ProviderAssetCandidate[]>;
+    resolveMetadata(request: ResolveMetadataRequest): Promise<ProviderAssetMetadata>;
+    requestDownload(request: RequestDownloadRequest): Promise<AcquisitionReceipt>;
+    download(request: DownloadRequest): Promise<PrivateStagingRef>;
+}
+interface ProviderRegistry {
+    get(providerId: ProviderId): ProviderSourceDescriptor;
+    list(): readonly ProviderSourceDescriptor[];
+}
+
+declare class SourceValidationError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+declare class SourceUnavailableError extends Error {
+    constructor();
+}
+declare class ProviderDisabledError extends Error {
+    constructor();
+}
+declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): T;
+declare function validateProviderId(value: unknown): ProviderId;
+declare function validateAssetIdentifier(value: unknown): AssetIdentifier;
+declare function validateRevision(value: unknown): Revision;
+declare function validateIdempotencyKey(value: unknown): string;
+declare function validateQuery(value: unknown): string;
+declare function validateCursor(value: unknown): string | undefined;
+declare function validateLimit(value: unknown): number;
+declare function sanitizeUntrustedText(value: unknown, maxLength: number): string;
+declare function validateSourcePage(value: unknown): string;
+declare function validateChecksum(value: unknown): string;
+declare function validateDescriptor(descriptor: ProviderSourceDescriptor): ProviderSourceDescriptor;
+declare function assertRightsApproved(rights: RightsEvidence): void;
+declare function normalizeCandidate(candidate: ProviderAssetCandidate, expectedProviderId: ProviderId): ProviderAssetCandidate;
+declare function normalizeMetadata(metadata: ProviderAssetMetadata, expectedProviderId: ProviderId): ProviderAssetMetadata;
+
+declare const DEFAULT_PROVIDER_DESCRIPTORS: readonly ProviderSourceDescriptor[];
+declare function createProviderRegistry(descriptors?: readonly ProviderSourceDescriptor[]): ProviderRegistry;
+
+interface ProviderConnectorDependencies {
+    readonly credentials: CredentialProvider;
+    readonly transport: ProviderTransport;
+    readonly normalizer: ProviderPayloadNormalizer;
+    readonly acquisition: AcquisitionPort;
+    readonly staging: PrivateStagingPort;
+    readonly checkpoints: CheckpointPort;
+}
+declare function createProviderConnector(descriptor: ProviderSourceDescriptor, dependencies: ProviderConnectorDependencies): ProviderConnector;
+
+interface FakeConnectorFixture {
+    readonly candidate: ProviderAssetCandidate;
+    readonly metadata?: Partial<ProviderAssetMetadata>;
+}
+declare function createMemoryCheckpoints(): CheckpointPort;
+declare function createFakeDependencies(providerId: ProviderId, fixture: FakeConnectorFixture): {
+    credentials: CredentialProvider;
+    transport: ProviderTransport;
+    normalizer: ProviderPayloadNormalizer;
+    acquisition: AcquisitionPort;
+    staging: PrivateStagingPort;
+    checkpoints: CheckpointPort;
+};
+declare function fixtureCandidate(providerId: string, assetId: string): ProviderAssetCandidate;
+
+export { type AcquiredContent, type AcquisitionPort, type AcquisitionReceipt, type AcquisitionRequest, type AssetIdentifier, CAPABILITIES, type Checkpoint, type CheckpointPort, type CredentialProvider, type CredentialRequest, DEFAULT_PROVIDER_DESCRIPTORS, type DownloadRequest, FEATURE_FLAGS, type FakeConnectorFixture, type PrivateStagingPort, type PrivateStagingRef, type ProviderAssetCandidate, type ProviderAssetMetadata, type ProviderConnector, type ProviderConnectorDependencies, type ProviderCredential, ProviderDisabledError, type ProviderId, type ProviderOperation, type ProviderPayloadNormalizer, type ProviderRegistry, type ProviderSourceDescriptor, type ProviderTransport, type ProviderTransportRequest, type RequestDownloadRequest, type ResolveMetadataRequest, type Revision, type RightsEvidence, type RightsEvidenceState, type RightsPolicyState, type SearchRequest, type SourceReviewState, SourceUnavailableError, SourceValidationError, type SupportedFormat, assertRightsApproved, createFakeDependencies, createMemoryCheckpoints, createProviderConnector, createProviderRegistry, deepFreeze, fixtureCandidate, normalizeCandidate, normalizeMetadata, sanitizeUntrustedText, validateAssetIdentifier, validateChecksum, validateCursor, validateDescriptor, validateIdempotencyKey, validateLimit, validateProviderId, validateQuery, validateRevision, validateSourcePage };

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+declare const FEATURE_FLAGS: Readonly<{
+    readonly parent: "asset.pipeline.unified-ai-assets.enabled";
+    readonly externalHarvest: "asset.pipeline.external-model-harvest.enabled";
+    readonly polyHaven: "asset.pipeline.provider.polyhaven.enabled";
+    readonly kenney: "asset.pipeline.provider.kenney.enabled";
+    readonly smithsonian: "asset.pipeline.provider.smithsonian.enabled";
+    readonly nasa: "asset.pipeline.provider.nasa.enabled";
+    readonly sketchfab: "asset.pipeline.provider.sketchfab.enabled";
+}>;
+declare const CAPABILITIES: Readonly<{
+    readonly sourceManage: "asset.source.manage";
+    readonly catalogReview: "asset.catalog.review";
+    readonly catalogRequest: "asset.catalog.request";
+}>;
+type ProviderId = string & {
+    readonly __providerId: unique symbol;
+};
+type AssetIdentifier = string & {
+    readonly __assetIdentifier: unique symbol;
+};
+type Revision = number & {
+    readonly __revision: unique symbol;
+};
+type ProviderOperation = "search" | "resolveMetadata" | "requestDownload" | "download";
+type SupportedFormat = "glb" | "gltf" | "fbx" | "obj" | "blend" | "zip" | "unknown";
+type SourceReviewState = "pending" | "approved" | "rejected";
+type RightsEvidenceState = "approved" | "unknown" | "changed";
+type RightsPolicyState = "commercial-redistribution" | "commercial-with-attribution" | "not-approved";
+interface ProviderSourceDescriptor {
+    readonly providerId: ProviderId;
+    readonly displayName: string;
+    readonly enabled: boolean;
+    readonly featureFlag: string;
+    readonly parentFeatureFlag: typeof FEATURE_FLAGS.parent;
+    readonly requiredCapabilities: readonly string[];
+    readonly operationalGates: readonly string[];
+    readonly sourceReview: SourceReviewState;
+    readonly rightsPolicy: RightsPolicyState;
+    readonly supportedFormats: readonly SupportedFormat[];
+}
+interface SearchRequest {
+    readonly providerId: ProviderId;
+    readonly query: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+interface ResolveMetadataRequest {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+}
+interface RequestDownloadRequest {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly idempotencyKey: string;
+    readonly expectedRevision?: Revision;
+}
+interface DownloadRequest {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly acquisitionId: string;
+}
+interface RightsEvidence {
+    readonly state: RightsEvidenceState;
+    readonly policy: RightsPolicyState;
+    readonly evidenceRevision: Revision;
+    readonly attributionRequired: boolean;
+}
+interface ProviderAssetCandidate {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly title: string;
+    readonly description: string;
+    readonly sourcePage: string;
+    readonly rights: RightsEvidence;
+    readonly supportedFormats: readonly SupportedFormat[];
+    readonly revision: Revision;
+    readonly disposition: "eligible" | "quarantined";
+}
+interface ProviderAssetMetadata extends ProviderAssetCandidate {
+    readonly creator?: string;
+    readonly attributionText?: string;
+}
+interface CredentialRequest {
+    readonly providerId: ProviderId;
+    readonly operation: ProviderOperation;
+}
+interface ProviderCredential {
+    readonly kind: "oauth" | "api-key" | "none";
+    readonly value: string;
+}
+interface CredentialProvider {
+    getCredential(request: CredentialRequest): Promise<ProviderCredential | null>;
+}
+interface ProviderTransportRequest {
+    readonly providerId: ProviderId;
+    readonly operation: "search" | "resolveMetadata";
+    readonly assetId?: AssetIdentifier;
+    readonly query?: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+interface ProviderTransport {
+    execute(request: ProviderTransportRequest, credential: ProviderCredential | null): Promise<unknown>;
+}
+interface ProviderPayloadNormalizer {
+    normalizeSearch(payload: unknown): readonly ProviderAssetCandidate[];
+    normalizeMetadata(payload: unknown): ProviderAssetMetadata;
+}
+interface AcquisitionRequest {
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly idempotencyKey: string;
+    readonly expectedRevision?: Revision;
+}
+interface AcquisitionReceipt {
+    readonly acquisitionId: string;
+    readonly providerId: ProviderId;
+    readonly assetId: AssetIdentifier;
+    readonly revision: Revision;
+    readonly status: "accepted" | "unavailable" | "quarantined";
+}
+interface AcquiredContent {
+    readonly acquisitionId: string;
+    readonly mediaType: string;
+    readonly byteLength: number;
+    readonly checksumSha256: string;
+}
+interface AcquisitionPort {
+    requestDownload(request: AcquisitionRequest): Promise<AcquisitionReceipt>;
+    download(request: DownloadRequest): Promise<AcquiredContent>;
+}
+interface PrivateStagingRef {
+    readonly stagingId: string;
+    readonly mediaType: string;
+    readonly byteLength: number;
+    readonly checksumSha256: string;
+    readonly expiresAt: string;
+}
+interface PrivateStagingPort {
+    stage(content: AcquiredContent): Promise<PrivateStagingRef>;
+}
+interface Checkpoint {
+    readonly idempotencyKey: string;
+    readonly receipt: AcquisitionReceipt;
+}
+interface CheckpointPort {
+    get(idempotencyKey: string): Promise<Checkpoint | null>;
+    put(checkpoint: Checkpoint): Promise<void>;
+}
+interface ProviderConnector {
+    readonly descriptor: ProviderSourceDescriptor;
+    search(request: SearchRequest): Promise<readonly ProviderAssetCandidate[]>;
+    resolveMetadata(request: ResolveMetadataRequest): Promise<ProviderAssetMetadata>;
+    requestDownload(request: RequestDownloadRequest): Promise<AcquisitionReceipt>;
+    download(request: DownloadRequest): Promise<PrivateStagingRef>;
+}
+interface ProviderRegistry {
+    get(providerId: ProviderId): ProviderSourceDescriptor;
+    list(): readonly ProviderSourceDescriptor[];
+}
+
+declare class SourceValidationError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+declare class SourceUnavailableError extends Error {
+    constructor();
+}
+declare class ProviderDisabledError extends Error {
+    constructor();
+}
+declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): T;
+declare function validateProviderId(value: unknown): ProviderId;
+declare function validateAssetIdentifier(value: unknown): AssetIdentifier;
+declare function validateRevision(value: unknown): Revision;
+declare function validateIdempotencyKey(value: unknown): string;
+declare function validateQuery(value: unknown): string;
+declare function validateCursor(value: unknown): string | undefined;
+declare function validateLimit(value: unknown): number;
+declare function sanitizeUntrustedText(value: unknown, maxLength: number): string;
+declare function validateSourcePage(value: unknown): string;
+declare function validateChecksum(value: unknown): string;
+declare function validateDescriptor(descriptor: ProviderSourceDescriptor): ProviderSourceDescriptor;
+declare function assertRightsApproved(rights: RightsEvidence): void;
+declare function normalizeCandidate(candidate: ProviderAssetCandidate, expectedProviderId: ProviderId): ProviderAssetCandidate;
+declare function normalizeMetadata(metadata: ProviderAssetMetadata, expectedProviderId: ProviderId): ProviderAssetMetadata;
+
+declare const DEFAULT_PROVIDER_DESCRIPTORS: readonly ProviderSourceDescriptor[];
+declare function createProviderRegistry(descriptors?: readonly ProviderSourceDescriptor[]): ProviderRegistry;
+
+interface ProviderConnectorDependencies {
+    readonly credentials: CredentialProvider;
+    readonly transport: ProviderTransport;
+    readonly normalizer: ProviderPayloadNormalizer;
+    readonly acquisition: AcquisitionPort;
+    readonly staging: PrivateStagingPort;
+    readonly checkpoints: CheckpointPort;
+}
+declare function createProviderConnector(descriptor: ProviderSourceDescriptor, dependencies: ProviderConnectorDependencies): ProviderConnector;
+
+interface FakeConnectorFixture {
+    readonly candidate: ProviderAssetCandidate;
+    readonly metadata?: Partial<ProviderAssetMetadata>;
+}
+declare function createMemoryCheckpoints(): CheckpointPort;
+declare function createFakeDependencies(providerId: ProviderId, fixture: FakeConnectorFixture): {
+    credentials: CredentialProvider;
+    transport: ProviderTransport;
+    normalizer: ProviderPayloadNormalizer;
+    acquisition: AcquisitionPort;
+    staging: PrivateStagingPort;
+    checkpoints: CheckpointPort;
+};
+declare function fixtureCandidate(providerId: string, assetId: string): ProviderAssetCandidate;
+
+export { type AcquiredContent, type AcquisitionPort, type AcquisitionReceipt, type AcquisitionRequest, type AssetIdentifier, CAPABILITIES, type Checkpoint, type CheckpointPort, type CredentialProvider, type CredentialRequest, DEFAULT_PROVIDER_DESCRIPTORS, type DownloadRequest, FEATURE_FLAGS, type FakeConnectorFixture, type PrivateStagingPort, type PrivateStagingRef, type ProviderAssetCandidate, type ProviderAssetMetadata, type ProviderConnector, type ProviderConnectorDependencies, type ProviderCredential, ProviderDisabledError, type ProviderId, type ProviderOperation, type ProviderPayloadNormalizer, type ProviderRegistry, type ProviderSourceDescriptor, type ProviderTransport, type ProviderTransportRequest, type RequestDownloadRequest, type ResolveMetadataRequest, type Revision, type RightsEvidence, type RightsEvidenceState, type RightsPolicyState, type SearchRequest, type SourceReviewState, SourceUnavailableError, SourceValidationError, type SupportedFormat, assertRightsApproved, createFakeDependencies, createMemoryCheckpoints, createProviderConnector, createProviderRegistry, deepFreeze, fixtureCandidate, normalizeCandidate, normalizeMetadata, sanitizeUntrustedText, validateAssetIdentifier, validateChecksum, validateCursor, validateDescriptor, validateIdempotencyKey, validateLimit, validateProviderId, validateQuery, validateRevision, validateSourcePage };