@ankhorage/contracts 7.3.0 → 7.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ankhorage/contracts
 
+## 7.4.0
+
+### Minor Changes
+
+- 06223da: Add provider-neutral object listing and readable URL resolution capabilities for app-authoring media storage adapters.
+
 ## 7.3.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # CONTRACTS
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v7.2.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v7.3.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Serializable app, action, theme, auth, and secret-store contracts for Ankhorage.
 

package/dist/storage.d.ts

@@ -45,6 +45,46 @@ export interface StoragePublicUrlInput {
 export interface StoragePublicUrlResult {
     publicUrl: string;
 }
+export interface StorageObjectMetadata {
+    storageId?: string;
+    bucket: string;
+    path: string;
+    contentType?: string;
+    sizeBytes?: number;
+    createdAt?: string;
+    updatedAt?: string;
+    etag?: string;
+}
+export interface StorageListInput {
+    storageId?: string;
+    bucket: string;
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface StorageListResult {
+    objects: readonly StorageObjectMetadata[];
+    nextCursor?: string;
+}
+export type StorageResolvedAccess = 'public' | 'signed';
+export interface StorageResolveInput {
+    storageId?: string;
+    bucket: string;
+    path: string;
+    access?: StorageResolvedAccess;
+    expiresInSeconds?: number;
+}
+export interface StorageResolvedAsset {
+    storageId?: string;
+    bucket: string;
+    path: string;
+    url: string;
+    access: StorageResolvedAccess;
+    expiresAt?: string;
+}
+export interface StorageResolveResult {
+    asset: StorageResolvedAsset;
+}
 export interface ImageMetadata {
     fileName?: string;
     sizeBytes?: number;
@@ -78,4 +118,19 @@ export interface StorageAdapter {
     publicUrl(input: StoragePublicUrlInput): Promise<StorageResult<StoragePublicUrlResult>>;
     getImageMetadata?(input: StorageAssetReference): Promise<StorageResult<ImageMetadata>>;
 }
+export interface StorageListAdapter {
+    list(input: StorageListInput): Promise<StorageResult<StorageListResult>>;
+}
+export interface StorageResolveAdapter {
+    resolve(input: StorageResolveInput): Promise<StorageResult<StorageResolveResult>>;
+}
+/**
+ * Storage capability required by the app-authoring media service.
+ *
+ * Remote URL import/ingest is intentionally not part of this low-level object-storage
+ * contract. It is a trusted service operation that can be implemented by reading the
+ * remote object and delegating to `upload` when ingestion is requested.
+ */
+export interface MediaStorageAdapter extends StorageAdapter, StorageListAdapter, StorageResolveAdapter {
+}
 //# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

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

package/dist/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"","sourcesContent":["export interface StorageAdapterError {\n  code: string;\n  message: string;\n  cause?: unknown;\n}\n\nexport type StorageOkResult<TData> = [TData] extends [void]\n  ? { ok: true; data?: undefined }\n  : { ok: true; data: TData };\n\nexport type StorageResult<TData = void> =\n  | StorageOkResult<TData>\n  | {\n      ok: false;\n      error: StorageAdapterError;\n    };\n\nexport interface StorageAssetReference {\n  storageId?: string;\n  bucket: string;\n  path: string;\n  publicUrl?: string;\n}\n\nexport interface StorageUploadInput {\n  storageId?: string;\n  bucket: string;\n  path: string;\n  body: Uint8Array;\n  contentType?: string;\n  cacheControl?: string;\n  upsert?: boolean;\n}\n\nexport interface StorageUploadResult {\n  asset: StorageAssetReference;\n}\n\nexport interface StorageRemoveInput {\n  storageId?: string;\n  bucket: string;\n  path: string;\n}\n\nexport interface StoragePublicUrlInput {\n  storageId?: string;\n  bucket: string;\n  path: string;\n}\n\nexport interface StoragePublicUrlResult {\n  publicUrl: string;\n}\n\nexport interface ImageMetadata {\n  fileName?: string;\n  sizeBytes?: number;\n  createdAt?: string;\n}\n\nexport interface StorageImageAssetSource {\n  kind: 'storage';\n  storageId?: string;\n  bucket: string;\n  path: string;\n  publicUrl?: string;\n  alt?: string;\n  width?: number;\n  height?: number;\n  contentType?: string;\n  metadata?: ImageMetadata;\n}\n\nexport interface UrlImageAssetSource {\n  kind: 'url';\n  url: string;\n  alt?: string;\n  width?: number;\n  height?: number;\n  contentType?: string;\n  metadata?: ImageMetadata;\n}\n\nexport type ImageAssetSource = StorageImageAssetSource | UrlImageAssetSource;\n\nexport interface StorageAdapter {\n  upload(input: StorageUploadInput): Promise<StorageResult<StorageUploadResult>>;\n  remove(input: StorageRemoveInput): Promise<StorageResult>;\n  publicUrl(input: StoragePublicUrlInput): Promise<StorageResult<StoragePublicUrlResult>>;\n  getImageMetadata?(input: StorageAssetReference): Promise<StorageResult<ImageMetadata>>;\n}\n"]}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"","sourcesContent":["export interface StorageAdapterError {\n  code: string;\n  message: string;\n  cause?: unknown;\n}\n\nexport type StorageOkResult<TData> = [TData] extends [void]\n  ? { ok: true; data?: undefined }\n  : { ok: true; data: TData };\n\nexport type StorageResult<TData = void> =\n  | StorageOkResult<TData>\n  | {\n      ok: false;\n      error: StorageAdapterError;\n    };\n\nexport interface StorageAssetReference {\n  storageId?: string;\n  bucket: string;\n  path: string;\n  publicUrl?: string;\n}\n\nexport interface StorageUploadInput {\n  storageId?: string;\n  bucket: string;\n  path: string;\n  body: Uint8Array;\n  contentType?: string;\n  cacheControl?: string;\n  upsert?: boolean;\n}\n\nexport interface StorageUploadResult {\n  asset: StorageAssetReference;\n}\n\nexport interface StorageRemoveInput {\n  storageId?: string;\n  bucket: string;\n  path: string;\n}\n\nexport interface StoragePublicUrlInput {\n  storageId?: string;\n  bucket: string;\n  path: string;\n}\n\nexport interface StoragePublicUrlResult {\n  publicUrl: string;\n}\n\nexport interface StorageObjectMetadata {\n  storageId?: string;\n  bucket: string;\n  path: string;\n  contentType?: string;\n  sizeBytes?: number;\n  createdAt?: string;\n  updatedAt?: string;\n  etag?: string;\n}\n\nexport interface StorageListInput {\n  storageId?: string;\n  bucket: string;\n  prefix?: string;\n  cursor?: string;\n  limit?: number;\n}\n\nexport interface StorageListResult {\n  objects: readonly StorageObjectMetadata[];\n  nextCursor?: string;\n}\n\nexport type StorageResolvedAccess = 'public' | 'signed';\n\nexport interface StorageResolveInput {\n  storageId?: string;\n  bucket: string;\n  path: string;\n  access?: StorageResolvedAccess;\n  expiresInSeconds?: number;\n}\n\nexport interface StorageResolvedAsset {\n  storageId?: string;\n  bucket: string;\n  path: string;\n  url: string;\n  access: StorageResolvedAccess;\n  expiresAt?: string;\n}\n\nexport interface StorageResolveResult {\n  asset: StorageResolvedAsset;\n}\n\nexport interface ImageMetadata {\n  fileName?: string;\n  sizeBytes?: number;\n  createdAt?: string;\n}\n\nexport interface StorageImageAssetSource {\n  kind: 'storage';\n  storageId?: string;\n  bucket: string;\n  path: string;\n  publicUrl?: string;\n  alt?: string;\n  width?: number;\n  height?: number;\n  contentType?: string;\n  metadata?: ImageMetadata;\n}\n\nexport interface UrlImageAssetSource {\n  kind: 'url';\n  url: string;\n  alt?: string;\n  width?: number;\n  height?: number;\n  contentType?: string;\n  metadata?: ImageMetadata;\n}\n\nexport type ImageAssetSource = StorageImageAssetSource | UrlImageAssetSource;\n\nexport interface StorageAdapter {\n  upload(input: StorageUploadInput): Promise<StorageResult<StorageUploadResult>>;\n  remove(input: StorageRemoveInput): Promise<StorageResult>;\n  publicUrl(input: StoragePublicUrlInput): Promise<StorageResult<StoragePublicUrlResult>>;\n  getImageMetadata?(input: StorageAssetReference): Promise<StorageResult<ImageMetadata>>;\n}\n\nexport interface StorageListAdapter {\n  list(input: StorageListInput): Promise<StorageResult<StorageListResult>>;\n}\n\nexport interface StorageResolveAdapter {\n  resolve(input: StorageResolveInput): Promise<StorageResult<StorageResolveResult>>;\n}\n\n/**\n * Storage capability required by the app-authoring media service.\n *\n * Remote URL import/ingest is intentionally not part of this low-level object-storage\n * contract. It is a trusted service operation that can be implemented by reading the\n * remote object and delegating to `upload` when ingestion is requested.\n */\nexport interface MediaStorageAdapter\n  extends StorageAdapter, StorageListAdapter, StorageResolveAdapter {}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "main": "./dist/index.js",
   "ankh": {
     "category": "contracts",

package/src/storage-capabilities.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'bun:test';
+
+import type { MediaStorageAdapter } from './storage';
+
+const adapter: MediaStorageAdapter = {
+  upload(input) {
+    return Promise.resolve({
+      ok: true,
+      data: {
+        asset: {
+          storageId: input.storageId,
+          bucket: input.bucket,
+          path: input.path,
+        },
+      },
+    });
+  },
+  remove() {
+    return Promise.resolve({ ok: true });
+  },
+  publicUrl(input) {
+    return Promise.resolve({
+      ok: true,
+      data: { publicUrl: `https://cdn.example.test/${input.bucket}/${input.path}` },
+    });
+  },
+  list(input) {
+    return Promise.resolve({
+      ok: true,
+      data: {
+        objects: [
+          {
+            storageId: input.storageId,
+            bucket: input.bucket,
+            path: `${input.prefix ?? ''}hero.png`,
+            contentType: 'image/png',
+            sizeBytes: 4096,
+          },
+        ],
+      },
+    });
+  },
+  resolve(input) {
+    return Promise.resolve({
+      ok: true,
+      data: {
+        asset: {
+          storageId: input.storageId,
+          bucket: input.bucket,
+          path: input.path,
+          url: `https://signed.example.test/${input.bucket}/${input.path}`,
+          access: input.access ?? 'signed',
+          expiresAt: '2026-08-12T10:00:00.000Z',
+        },
+      },
+    });
+  },
+};
+
+describe('media storage capabilities', () => {
+  it('lists normalized provider-neutral object metadata', async () => {
+    const result = await adapter.list({
+      storageId: 'primary',
+      bucket: 'media',
+      prefix: 'authoring/',
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      data: {
+        objects: [
+          {
+            storageId: 'primary',
+            bucket: 'media',
+            path: 'authoring/hero.png',
+            contentType: 'image/png',
+            sizeBytes: 4096,
+          },
+        ],
+      },
+    });
+  });
+
+  it('resolves a stable storage identity to a runtime-readable URL', async () => {
+    const result = await adapter.resolve({
+      storageId: 'primary',
+      bucket: 'media',
+      path: 'authoring/hero.png',
+      access: 'signed',
+      expiresInSeconds: 900,
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      data: {
+        asset: {
+          storageId: 'primary',
+          bucket: 'media',
+          path: 'authoring/hero.png',
+          url: 'https://signed.example.test/media/authoring/hero.png',
+          access: 'signed',
+          expiresAt: '2026-08-12T10:00:00.000Z',
+        },
+      },
+    });
+  });
+});

package/src/storage.ts

@@ -52,6 +52,53 @@ export interface StoragePublicUrlResult {
   publicUrl: string;
 }
 
+export interface StorageObjectMetadata {
+  storageId?: string;
+  bucket: string;
+  path: string;
+  contentType?: string;
+  sizeBytes?: number;
+  createdAt?: string;
+  updatedAt?: string;
+  etag?: string;
+}
+
+export interface StorageListInput {
+  storageId?: string;
+  bucket: string;
+  prefix?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface StorageListResult {
+  objects: readonly StorageObjectMetadata[];
+  nextCursor?: string;
+}
+
+export type StorageResolvedAccess = 'public' | 'signed';
+
+export interface StorageResolveInput {
+  storageId?: string;
+  bucket: string;
+  path: string;
+  access?: StorageResolvedAccess;
+  expiresInSeconds?: number;
+}
+
+export interface StorageResolvedAsset {
+  storageId?: string;
+  bucket: string;
+  path: string;
+  url: string;
+  access: StorageResolvedAccess;
+  expiresAt?: string;
+}
+
+export interface StorageResolveResult {
+  asset: StorageResolvedAsset;
+}
+
 export interface ImageMetadata {
   fileName?: string;
   sizeBytes?: number;
@@ -89,3 +136,21 @@ export interface StorageAdapter {
   publicUrl(input: StoragePublicUrlInput): Promise<StorageResult<StoragePublicUrlResult>>;
   getImageMetadata?(input: StorageAssetReference): Promise<StorageResult<ImageMetadata>>;
 }
+
+export interface StorageListAdapter {
+  list(input: StorageListInput): Promise<StorageResult<StorageListResult>>;
+}
+
+export interface StorageResolveAdapter {
+  resolve(input: StorageResolveInput): Promise<StorageResult<StorageResolveResult>>;
+}
+
+/**
+ * Storage capability required by the app-authoring media service.
+ *
+ * Remote URL import/ingest is intentionally not part of this low-level object-storage
+ * contract. It is a trusted service operation that can be implemented by reading the
+ * remote object and delegating to `upload` when ingestion is requested.
+ */
+export interface MediaStorageAdapter
+  extends StorageAdapter, StorageListAdapter, StorageResolveAdapter {}