@ankhorage/contracts 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ankhorage/contracts
 
+## 1.2.0
+
+### Minor Changes
+
+- f773215: Add provider-neutral storage and image asset contracts.
+
+  This introduces serializable storage asset references, a `StorageAdapter` contract for upload, remove, and public URL workflows, and manifest-safe `ImageAssetSource` variants for storage-backed and URL-backed images.
+
+  The storage upload boundary uses `Uint8Array` only, avoids DOM-specific `File`/`Blob` types, and keeps storage identity provider-neutral through `storageId`, `bucket`, and `path`.
+
 ## 1.1.1
 
 ### Patch Changes

package/README.md

@@ -23,6 +23,7 @@ Shared public contracts for Ankhorage packages and standalone provider packages.
 import type { AppManifest } from '@ankhorage/contracts';
 import type { AuthAdapter } from '@ankhorage/contracts/auth';
 import type { DbAdapter } from '@ankhorage/contracts/db';
+import type { StorageAdapter } from '@ankhorage/contracts/storage';
 ```
 
 Contracts keeps theme configuration serializable. Color validation, harmony,

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './auth';
 export * from './db';
+export * from './storage';
 export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './auth';
 export * from './db';
+export * from './storage';
 export * from './types';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC","sourcesContent":["export * from './auth';\nexport * from './db';\nexport * from './types';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC","sourcesContent":["export * from './auth';\nexport * from './db';\nexport * from './storage';\nexport * from './types';\n"]}

package/dist/storage.d.ts

@@ -0,0 +1,81 @@
+export interface StorageAdapterError {
+    code: string;
+    message: string;
+    cause?: unknown;
+}
+export type StorageOkResult<TData> = [TData] extends [void] ? {
+    ok: true;
+    data?: undefined;
+} : {
+    ok: true;
+    data: TData;
+};
+export type StorageResult<TData = void> = StorageOkResult<TData> | {
+    ok: false;
+    error: StorageAdapterError;
+};
+export interface StorageAssetReference {
+    storageId?: string;
+    bucket: string;
+    path: string;
+    publicUrl?: string;
+}
+export interface StorageUploadInput {
+    storageId?: string;
+    bucket: string;
+    path: string;
+    body: Uint8Array;
+    contentType?: string;
+    cacheControl?: string;
+    upsert?: boolean;
+}
+export interface StorageUploadResult {
+    asset: StorageAssetReference;
+}
+export interface StorageRemoveInput {
+    storageId?: string;
+    bucket: string;
+    path: string;
+}
+export interface StoragePublicUrlInput {
+    storageId?: string;
+    bucket: string;
+    path: string;
+}
+export interface StoragePublicUrlResult {
+    publicUrl: string;
+}
+export interface ImageMetadata {
+    fileName?: string;
+    sizeBytes?: number;
+    createdAt?: string;
+}
+export interface StorageImageAssetSource {
+    kind: 'storage';
+    storageId?: string;
+    bucket: string;
+    path: string;
+    publicUrl?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    contentType?: string;
+    metadata?: ImageMetadata;
+}
+export interface UrlImageAssetSource {
+    kind: 'url';
+    url: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    contentType?: string;
+    metadata?: ImageMetadata;
+}
+export type ImageAssetSource = StorageImageAssetSource | UrlImageAssetSource;
+export interface StorageAdapter {
+    upload(input: StorageUploadInput): Promise<StorageResult<StorageUploadResult>>;
+    remove(input: StorageRemoveInput): Promise<StorageResult>;
+    publicUrl(input: StoragePublicUrlInput): Promise<StorageResult<StoragePublicUrlResult>>;
+    getImageMetadata?(input: StorageAssetReference): Promise<StorageResult<ImageMetadata>>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

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

package/dist/storage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +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"]}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "main": "./dist/index.js",
   "dependencies": {
-    "@ankhorage/color-theory": "^0.0.3"
+    "@ankhorage/color-theory": "^0.0.4"
   },
   "devDependencies": {
     "@ankhorage/devtools": "^1.0.0",
@@ -24,6 +24,10 @@
     "./db": {
       "types": "./dist/db.d.ts",
       "default": "./dist/db.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "default": "./dist/storage.js"
     }
   },
   "description": "Serializable app, action, and theme config contracts for Ankhorage.",

package/src/contracts.test.ts

@@ -13,7 +13,11 @@ import {
   type AuthFlowConfig,
   type AuthSpec,
   DEPLOYMENT_TARGETS,
+  type ImageAssetSource,
   NAVIGATOR_TYPES,
+  type StoragePublicUrlResult,
+  type StorageResult,
+  type StorageUploadResult,
   type ThemeConfig,
   type ThemeModeConfig,
 } from './index';
@@ -164,4 +168,54 @@ describe('contracts', () => {
     expect(auth.flow?.signInRoute).toBe('/sign-in');
     expect(auth.signUp?.signUpPolicy).toBe('requireVerification');
   });
+
+  it('requires data for successful non-void storage results', () => {
+    const uploaded: StorageResult<StorageUploadResult> = {
+      ok: true,
+      data: {
+        asset: {
+          storageId: 'default',
+          bucket: 'app-assets',
+          path: 'images/logo.png',
+        },
+      },
+    };
+
+    expect(uploaded.ok).toBe(true);
+    expect(uploaded.data.asset.bucket).toBe('app-assets');
+    expect(uploaded.data.asset.path).toBe('images/logo.png');
+  });
+
+  it('accepts a public URL result for storage assets', () => {
+    const resolved: StorageResult<StoragePublicUrlResult> = {
+      ok: true,
+      data: {
+        publicUrl: 'https://cdn.example.com/app-assets/images/logo.png',
+      },
+    };
+
+    expect(resolved.ok).toBe(true);
+    expect(resolved.data.publicUrl).toContain('https://');
+  });
+
+  it('serializes image asset sources without provider-specific runtime values', () => {
+    const source: ImageAssetSource = {
+      kind: 'storage',
+      storageId: 'default',
+      bucket: 'app-assets',
+      path: 'images/logo.png',
+      publicUrl: 'https://cdn.example.com/app-assets/images/logo.png',
+      alt: 'Logo',
+      width: 1200,
+      height: 630,
+      contentType: 'image/png',
+      metadata: {
+        fileName: 'logo.png',
+        sizeBytes: 123456,
+        createdAt: '2026-05-10T00:00:00.000Z',
+      },
+    };
+
+    expect(JSON.parse(JSON.stringify(source))).toEqual(source);
+  });
 });

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './auth';
 export * from './db';
+export * from './storage';
 export * from './types';

package/src/storage.ts

@@ -0,0 +1,91 @@
+export interface StorageAdapterError {
+  code: string;
+  message: string;
+  cause?: unknown;
+}
+
+export type StorageOkResult<TData> = [TData] extends [void]
+  ? { ok: true; data?: undefined }
+  : { ok: true; data: TData };
+
+export type StorageResult<TData = void> =
+  | StorageOkResult<TData>
+  | {
+      ok: false;
+      error: StorageAdapterError;
+    };
+
+export interface StorageAssetReference {
+  storageId?: string;
+  bucket: string;
+  path: string;
+  publicUrl?: string;
+}
+
+export interface StorageUploadInput {
+  storageId?: string;
+  bucket: string;
+  path: string;
+  body: Uint8Array;
+  contentType?: string;
+  cacheControl?: string;
+  upsert?: boolean;
+}
+
+export interface StorageUploadResult {
+  asset: StorageAssetReference;
+}
+
+export interface StorageRemoveInput {
+  storageId?: string;
+  bucket: string;
+  path: string;
+}
+
+export interface StoragePublicUrlInput {
+  storageId?: string;
+  bucket: string;
+  path: string;
+}
+
+export interface StoragePublicUrlResult {
+  publicUrl: string;
+}
+
+export interface ImageMetadata {
+  fileName?: string;
+  sizeBytes?: number;
+  createdAt?: string;
+}
+
+export interface StorageImageAssetSource {
+  kind: 'storage';
+  storageId?: string;
+  bucket: string;
+  path: string;
+  publicUrl?: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  contentType?: string;
+  metadata?: ImageMetadata;
+}
+
+export interface UrlImageAssetSource {
+  kind: 'url';
+  url: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  contentType?: string;
+  metadata?: ImageMetadata;
+}
+
+export type ImageAssetSource = StorageImageAssetSource | UrlImageAssetSource;
+
+export interface StorageAdapter {
+  upload(input: StorageUploadInput): Promise<StorageResult<StorageUploadResult>>;
+  remove(input: StorageRemoveInput): Promise<StorageResult>;
+  publicUrl(input: StoragePublicUrlInput): Promise<StorageResult<StoragePublicUrlResult>>;
+  getImageMetadata?(input: StorageAssetReference): Promise<StorageResult<ImageMetadata>>;
+}