@symbiote-native/media-library 0.1.0

package/src/core/types.ts

@@ -0,0 +1,163 @@
+import type { PermissionResponse } from 'expo-modules-core';
+
+export type IGranularPermission = 'audio' | 'photo' | 'video';
+
+export type IMediaLibraryMediaTypeValue =
+  'audio' | 'photo' | 'video' | 'unknown' | 'pairedVideo';
+
+/** @platform android 14+ */
+export type IMediaLibraryMediaTypeFilter = 'photo' | 'video';
+
+export type IMediaLibrarySortByKey =
+  | 'default'
+  | 'mediaType'
+  | 'width'
+  | 'height'
+  | 'creationTime'
+  | 'modificationTime'
+  | 'duration';
+
+export type IMediaLibrarySortByValue =
+  [IMediaLibrarySortByKey, boolean] | IMediaLibrarySortByKey;
+
+export type IMediaLibraryMediaTypeObject = {
+  audio: 'audio';
+  photo: 'photo';
+  video: 'video';
+  unknown: 'unknown';
+};
+
+export type IMediaLibrarySortByObject = {
+  default: 'default';
+  mediaType: 'mediaType';
+  width: 'width';
+  height: 'height';
+  creationTime: 'creationTime';
+  modificationTime: 'modificationTime';
+  duration: 'duration';
+};
+
+/** @platform ios */
+export type IMediaLibraryMediaSubtype =
+  | 'depthEffect'
+  | 'hdr'
+  | 'highFrameRate'
+  | 'livePhoto'
+  | 'panorama'
+  | 'screenshot'
+  | 'stream'
+  | 'timelapse'
+  | 'spatialMedia'
+  | 'videoCinematic';
+
+export type IMediaLibraryLocation = {
+  latitude: number;
+  longitude: number;
+};
+
+export type IMediaLibraryAsset = {
+  id: string;
+  filename: string;
+  /** `ph://*` (iOS), `file://*` (Android) */
+  uri: string;
+  mediaType: IMediaLibraryMediaTypeValue;
+  /** @platform ios */
+  mediaSubtypes?: IMediaLibraryMediaSubtype[];
+  width: number;
+  height: number;
+  creationTime: number;
+  modificationTime: number;
+  /** Seconds, for audio/video assets. */
+  duration: number;
+  /** @platform android */
+  albumId?: string;
+};
+
+export type IMediaLibraryAssetInfo = IMediaLibraryAsset & {
+  localUri?: string;
+  location?: IMediaLibraryLocation;
+  exif?: object;
+  /** @platform ios */
+  isFavorite?: boolean;
+  /** Only set when `shouldDownloadFromNetwork` is `false`. @platform ios */
+  isNetworkAsset?: boolean;
+  /** 1-8, see the EXIF orientation spec. Only for `mediaType: 'photo'`. @platform ios */
+  orientation?: number;
+  /** The video paired with a Live Photo. @platform ios */
+  pairedVideoAsset?: IMediaLibraryAsset | null;
+};
+
+export type IMediaLibraryAssetInfoQueryOptions = {
+  /** @default true — iOS iCloud assets only */
+  shouldDownloadFromNetwork?: boolean;
+};
+
+export type IMediaLibraryAssetsChangeEvent = {
+  /** `false` on Android — the platform never reports incremental detail. */
+  hasIncrementalChanges: boolean;
+  insertedAssets?: IMediaLibraryAsset[];
+  deletedAssets?: IMediaLibraryAsset[];
+  updatedAssets?: IMediaLibraryAsset[];
+};
+
+export type IMediaLibraryAlbumType = 'album' | 'moment' | 'smartAlbum';
+
+export type IMediaLibraryAlbum = {
+  id: string;
+  title: string;
+  assetCount: number;
+  /** @platform ios */
+  type?: IMediaLibraryAlbumType;
+  /** Only for `type: 'moment'`. @platform ios */
+  startTime: number;
+  /** Only for `type: 'moment'`. @platform ios */
+  endTime: number;
+  /** Only for `type: 'moment'`. @platform ios */
+  approximateLocation?: IMediaLibraryLocation;
+  /** Only for `type: 'moment'`. @platform ios */
+  locationNames?: string[];
+};
+
+export type IMediaLibraryAlbumsOptions = {
+  includeSmartAlbums?: boolean;
+};
+
+export type IMediaLibraryAssetRef = IMediaLibraryAsset | string;
+export type IMediaLibraryAlbumRef = IMediaLibraryAlbum | string;
+
+export type IMediaLibraryAssetsOptions = {
+  /** @default 20 */
+  first?: number;
+  /** Pass the previous page's `endCursor` to fetch the next page. */
+  after?: IMediaLibraryAssetRef;
+  album?: IMediaLibraryAlbumRef;
+  /** All keys sort descending by default; pass `[key, true]` for ascending. */
+  sortBy?: IMediaLibrarySortByValue[] | IMediaLibrarySortByValue;
+  /** @default MediaType.photo */
+  mediaType?: IMediaLibraryMediaTypeValue[] | IMediaLibraryMediaTypeValue;
+  /** @platform ios */
+  mediaSubtypes?: IMediaLibraryMediaSubtype[] | IMediaLibraryMediaSubtype;
+  createdAfter?: Date | number;
+  createdBefore?: Date | number;
+  /** @default false @platform android */
+  resolveWithFullInfo?: boolean;
+};
+
+export type IMediaLibraryPagedInfo<T> = {
+  assets: T[];
+  /** iOS: the ID of the last fetched asset. Android: its index. */
+  endCursor: string;
+  hasNextPage: boolean;
+  totalCount: number;
+};
+
+export type IMediaLibraryPermissionResponse = PermissionResponse & {
+  /**
+   * - `'all'` — full library access
+   * - `'limited'` — only selected photos (Android 14+, iOS 14+)
+   * - `'none'` — denied or not yet granted
+   */
+  accessPrivileges?: 'all' | 'limited' | 'none';
+};
+
+export type { PermissionResponse };

package/src/next/album.ts

@@ -0,0 +1,13 @@
+import { expoMediaLibraryNext } from './native-module';
+import { Asset } from './asset';
+
+/**
+ * A media album (collection of assets) on the device, matching upstream's own trivial subclass
+ * for every method but `getAssets()` — same reason as Query.exe(), see query.ts.
+ */
+export class Album extends expoMediaLibraryNext.Album {
+  override async getAssets(): Promise<Asset[]> {
+    const results = await super.getAssets();
+    return results.map(result => new Asset(result.id));
+  }
+}

package/src/next/asset.ts

@@ -0,0 +1,51 @@
+import { Platform } from 'react-native';
+import { UnavailabilityError } from 'expo-modules-core';
+import { expoMediaLibraryNext } from './native-module';
+import type { MediaSubtype } from './types';
+
+/**
+ * A single media asset on the device (image, video, or audio). Four getters are iOS-only on
+ * upstream's own native side; guarded here to fail with the same `UnavailabilityError` upstream
+ * throws rather than whatever the Android native method happens to do when called anyway.
+ */
+export class Asset extends expoMediaLibraryNext.Asset {
+  override getMediaSubtypes(): Promise<MediaSubtype[]> {
+    if (Platform.OS !== 'ios') {
+      throw new UnavailabilityError(
+        'MediaLibrary',
+        'getMediaSubtypes is only available on iOS',
+      );
+    }
+    return super.getMediaSubtypes() as Promise<MediaSubtype[]>;
+  }
+
+  override getLivePhotoVideoUri(): Promise<string | null> {
+    if (Platform.OS !== 'ios') {
+      throw new UnavailabilityError(
+        'MediaLibrary',
+        'getLivePhotoVideoUri is only available on iOS',
+      );
+    }
+    return super.getLivePhotoVideoUri();
+  }
+
+  override getIsInCloud(): Promise<boolean> {
+    if (Platform.OS !== 'ios') {
+      throw new UnavailabilityError(
+        'MediaLibrary',
+        'getIsInCloud is only available on iOS',
+      );
+    }
+    return super.getIsInCloud();
+  }
+
+  override getOrientation(): Promise<number | null> {
+    if (Platform.OS !== 'ios') {
+      throw new UnavailabilityError(
+        'MediaLibrary',
+        'getOrientation is only available on iOS',
+      );
+    }
+    return super.getOrientation();
+  }
+}

package/src/next/index.ts

@@ -0,0 +1,82 @@
+import { Platform } from 'react-native';
+import {
+  createPermissionHook,
+  type EventSubscription,
+} from 'expo-modules-core';
+import { expoMediaLibraryNext } from './native-module';
+import type {
+  IGranularPermission,
+  IMediaLibraryAssetsChangeEvent,
+  IMediaLibraryNextPermissionResponse,
+  IMediaTypeFilter,
+  IPermissionHookOptions,
+} from './types';
+
+export { Query } from './query';
+export { Asset } from './asset';
+export { Album } from './album';
+export * from './types';
+
+/**
+ * @param granularPermissions Only has an effect on Android 13+. Defaults to every possible
+ * permission — make sure your app manifest requests everything you pass here.
+ */
+export async function requestPermissionsAsync(
+  writeOnly: boolean = false,
+  granularPermissions?: IGranularPermission[],
+): Promise<IMediaLibraryNextPermissionResponse> {
+  if (Platform.OS === 'android') {
+    return expoMediaLibraryNext.requestPermissionsAsync(
+      writeOnly,
+      granularPermissions,
+    );
+  }
+  return expoMediaLibraryNext.requestPermissionsAsync(writeOnly);
+}
+
+export async function getPermissionsAsync(
+  writeOnly: boolean = false,
+  granularPermissions?: IGranularPermission[],
+): Promise<IMediaLibraryNextPermissionResponse> {
+  if (Platform.OS === 'android') {
+    return expoMediaLibraryNext.getPermissionsAsync(
+      writeOnly,
+      granularPermissions,
+    );
+  }
+  return expoMediaLibraryNext.getPermissionsAsync(writeOnly);
+}
+
+export const usePermissions = createPermissionHook<
+  IMediaLibraryNextPermissionResponse,
+  IPermissionHookOptions
+>({
+  getMethod: (options?: IPermissionHookOptions) =>
+    getPermissionsAsync(options?.writeOnly, options?.granularPermissions),
+  requestMethod: (options?: IPermissionHookOptions) =>
+    requestPermissionsAsync(options?.writeOnly, options?.granularPermissions),
+});
+
+/**
+ * Allows the user to update the assets your app has access to. Only a no-op unless the user
+ * previously granted `'limited'` access.
+ */
+export async function presentPermissionsPicker(
+  mediaTypes?: IMediaTypeFilter[],
+): Promise<void> {
+  return expoMediaLibraryNext.presentPermissionsPicker(mediaTypes);
+}
+
+/**
+ * Subscribes for updates in the user's media library. On Android it's invoked with an empty
+ * object — only iOS reports `insertedAssets`/`deletedAssets`/`updatedAssets`.
+ */
+export function addListener(
+  listener: (event: IMediaLibraryAssetsChangeEvent) => void,
+): EventSubscription {
+  return expoMediaLibraryNext.addListener('mediaLibraryDidChange', listener);
+}
+
+export function removeAllListeners(): void {
+  expoMediaLibraryNext.removeAllListeners('mediaLibraryDidChange');
+}

package/src/next/native-module.ts

@@ -0,0 +1,116 @@
+import { requireNativeModule, type EventSubscription } from 'expo-modules-core';
+import type {
+  AssetField,
+  IAssetFieldValueMap,
+  IAssetInfo,
+  IAssetMetadata,
+  ISortDescriptor,
+} from './types';
+
+// `declare class` (matching upstream's own ExpoMediaLibraryNext.ts pattern), not a flat object
+// type with a self-referential `new(...): T` construct signature — the latter makes TypeScript
+// report spurious `override` errors on the JS classes that `extends` these
+// (packages/file-system/src/next/native-module.ts carries the same note, found the hard way there).
+
+// Every chained filter method returns `this`, not the concrete `NativeMediaLibraryQuery` type
+// upstream's own ambient declaration uses (harmless for them - they never subclass `Query`).
+// Our own `Query` (query.ts) DOES subclass it to override `exe()`, and a `this`-typed return is
+// what lets that override survive a chain: `new Query().orderBy(...).limit(...)` would otherwise
+// statically widen back to the base `NativeMediaLibraryQuery` after the first chained call,
+// silently routing `.exe()` to the base implementation instead of our override.
+export declare class NativeMediaLibraryQuery {
+  constructor();
+  eq<T extends AssetField>(field: T, value: IAssetFieldValueMap[T]): this;
+  within<T extends AssetField>(field: T, value: IAssetFieldValueMap[T][]): this;
+  gt(field: AssetField, value: number): this;
+  gte(field: AssetField, value: number): this;
+  lt(field: AssetField, value: number): this;
+  lte(field: AssetField, value: number): this;
+  limit(limit: number): this;
+  offset(offset: number): this;
+  orderBy(sortDescriptors: ISortDescriptor | AssetField): this;
+  album(album: NativeMediaLibraryAlbum): this;
+  exe(): Promise<NativeMediaLibraryAsset[]>;
+  exeForMetadata(): Promise<IAssetMetadata[]>;
+}
+
+export declare class NativeMediaLibraryAsset {
+  constructor(id: string);
+  id: string;
+  getCreationTime(): Promise<number | null>;
+  getDuration(): Promise<number | null>;
+  getFilename(): Promise<string>;
+  getHeight(): Promise<number>;
+  getMediaType(): Promise<string>;
+  getMediaSubtypes(): Promise<string[]>;
+  getLivePhotoVideoUri(): Promise<string | null>;
+  getIsInCloud(): Promise<boolean>;
+  getOrientation(): Promise<number | null>;
+  getModificationTime(): Promise<number | null>;
+  getShape(): Promise<{ width: number; height: number } | null>;
+  getUri(): Promise<string>;
+  getWidth(): Promise<number>;
+  getInfo(): Promise<IAssetInfo>;
+  getAlbums(): Promise<NativeMediaLibraryAlbum[]>;
+  getLocation(): Promise<{ latitude: number; longitude: number } | null>;
+  getExif(): Promise<Record<string, unknown>>;
+  delete(): Promise<void>;
+  getFavorite(): Promise<boolean>;
+  setFavorite(isFavorite: boolean): Promise<void>;
+  static create(
+    filePath: string,
+    album?: NativeMediaLibraryAlbum,
+  ): Promise<NativeMediaLibraryAsset>;
+  static delete(assets: NativeMediaLibraryAsset[]): Promise<void>;
+}
+
+export declare class NativeMediaLibraryAlbum {
+  constructor(id: string);
+  id: string;
+  getAssets(): Promise<NativeMediaLibraryAsset[]>;
+  getTitle(): Promise<string>;
+  delete(): Promise<void>;
+  add(
+    assets: NativeMediaLibraryAsset | NativeMediaLibraryAsset[],
+  ): Promise<void>;
+  removeAssets(assets: NativeMediaLibraryAsset[]): Promise<void>;
+  static create(
+    name: string,
+    assetsRefs: string[] | NativeMediaLibraryAsset[],
+    moveAssets?: boolean,
+  ): Promise<NativeMediaLibraryAlbum>;
+  static delete(
+    albums: NativeMediaLibraryAlbum[],
+    deleteAssets?: boolean,
+  ): Promise<void>;
+  static get(title: string): Promise<NativeMediaLibraryAlbum | null>;
+  static getAll(): Promise<NativeMediaLibraryAlbum[]>;
+}
+
+export type INativeMediaLibraryNextModule = {
+  Query: typeof NativeMediaLibraryQuery;
+  Asset: typeof NativeMediaLibraryAsset;
+  Album: typeof NativeMediaLibraryAlbum;
+  getPermissionsAsync(
+    writeOnly?: boolean,
+    granularPermissions?: string[],
+  ): Promise<import('expo-modules-core').PermissionResponse>;
+  requestPermissionsAsync(
+    writeOnly?: boolean,
+    granularPermissions?: string[],
+  ): Promise<import('expo-modules-core').PermissionResponse>;
+  presentPermissionsPicker(mediaTypes?: string[]): Promise<void>;
+  addListener(
+    eventName: 'mediaLibraryDidChange',
+    listener: (event: {
+      hasIncrementalChanges: boolean;
+      insertedAssets?: string[];
+      deletedAssets?: string[];
+      updatedAssets?: string[];
+    }) => void,
+  ): EventSubscription;
+  removeAllListeners(eventName: 'mediaLibraryDidChange'): void;
+};
+
+export const expoMediaLibraryNext =
+  requireNativeModule<INativeMediaLibraryNextModule>('ExpoMediaLibraryNext');

package/src/next/query.ts

@@ -0,0 +1,17 @@
+import { expoMediaLibraryNext } from './native-module';
+import { Asset } from './asset';
+
+/**
+ * A query builder over the media library, matching upstream's own trivial subclass
+ * (`export class Query extends ExpoMediaLibraryNext.Query {}`) for every method but `exe()`:
+ * the native call constructs its results off the BASE native asset class, never our own `Asset`
+ * (asset.ts) — so without this override, a query result's iOS-only getters silently skip the
+ * platform guard every other `Asset` gets. Re-wrapping by id is cheap (a shared-object handle,
+ * not a data copy) and keeps `exe()` consistent with every other way of obtaining an `Asset`.
+ */
+export class Query extends expoMediaLibraryNext.Query {
+  override async exe(): Promise<Asset[]> {
+    const results = await super.exe();
+    return results.map(result => new Asset(result.id));
+  }
+}

package/src/next/types.ts

@@ -0,0 +1,106 @@
+import type { PermissionResponse } from 'expo-modules-core';
+
+export enum AssetField {
+  CREATION_TIME = 'creationTime',
+  MODIFICATION_TIME = 'modificationTime',
+  MEDIA_TYPE = 'mediaType',
+  WIDTH = 'width',
+  HEIGHT = 'height',
+  DURATION = 'duration',
+  IS_FAVORITE = 'isFavorite',
+}
+
+export enum MediaType {
+  UNKNOWN = 'unknown',
+  IMAGE = 'image',
+  AUDIO = 'audio',
+  VIDEO = 'video',
+}
+
+export enum MediaSubtype {
+  DEPTH_EFFECT = 'depthEffect',
+  HDR = 'hdr',
+  HIGH_FRAME_RATE = 'highFrameRate',
+  LIVE_PHOTO = 'livePhoto',
+  PANORAMA = 'panorama',
+  SCREENSHOT = 'screenshot',
+  STREAM = 'stream',
+  TIME_LAPSE = 'timelapse',
+  SPATIAL_MEDIA = 'spatialMedia',
+  VIDEO_CINEMATIC = 'videoCinematic',
+}
+
+export type IAssetFieldValueMap = {
+  [AssetField.CREATION_TIME]: number;
+  [AssetField.MODIFICATION_TIME]: number;
+  [AssetField.MEDIA_TYPE]: MediaType;
+  [AssetField.WIDTH]: number;
+  [AssetField.HEIGHT]: number;
+  [AssetField.DURATION]: number;
+  [AssetField.IS_FAVORITE]: boolean;
+};
+
+export type ISortDescriptor = {
+  key: AssetField;
+  ascending?: boolean;
+};
+
+export type IShape = {
+  width: number;
+  height: number;
+};
+
+export type ILocation = {
+  latitude: number;
+  longitude: number;
+};
+
+export type IAssetInfo = {
+  id: string;
+  filename: string;
+  uri: string;
+  mediaType: MediaType;
+  width: number;
+  height: number;
+  duration: number | null;
+  creationTime: number | null;
+  modificationTime: number | null;
+  isFavorite: boolean;
+};
+
+export type IAssetMetadata = {
+  id: string;
+  filename: string | null;
+  mediaType: MediaType;
+  width: number | null;
+  height: number | null;
+  duration: number | null;
+  creationTime: number | null;
+  modificationTime: number | null;
+  isFavorite: boolean;
+};
+
+export type IGranularPermission = 'audio' | 'photo' | 'video';
+
+export type IMediaTypeFilter = 'photo' | 'video';
+
+export type IMediaLibraryAssetsChangeEvent = {
+  hasIncrementalChanges: boolean;
+  insertedAssets?: string[];
+  deletedAssets?: string[];
+  updatedAssets?: string[];
+};
+
+export type IPermissionHookOptions = {
+  writeOnly?: boolean;
+  granularPermissions?: IGranularPermission[];
+};
+
+export type IMediaLibraryNextPermissionResponse = PermissionResponse & {
+  /**
+   * - `'all'` — full library access
+   * - `'limited'` — only selected photos (Android 14+, iOS 14+)
+   * - `'none'` — denied or not yet granted
+   */
+  accessPrivileges?: 'all' | 'limited' | 'none';
+};