JavaScript API

import * as Rollup from 'expo-rollup';

function configure(publishableKey: string, options?: IndexOptionsInput): Promise<void>

function requestPhotoAccess(): Promise<PhotoAccess>

function startIndexing(): Promise<void>

function getIndexOptions(): Promise<IndexOptions>

function reset(): Promise<void>

function useIndexingState(): IndexingState | null

function getIndexingState(): Promise<IndexingState>

function addIndexingStateListener(listener: (state: IndexingState) => void): { remove(): void }

function isSearchable(state: IndexingState | null | undefined): boolean

function search(text: string): Promise<SearchResults>

function query(question: string): Promise<Answer>

function profile<T = { [key: string]: JSONValue }>(schema: object): Promise<Profile<T>>

const isAvailable: boolean
const sdkVersion: string | null

const span: {
  days(value: number): Span;
  weeks(value: number): Span;
  months(value: number): Span;
  years(value: number): Span;
};

const indexWindow: {
  growing(from: Span): IndexWindow;
  sliding(recent: Span): IndexWindow;
};

await Rollup.configure('rk_live_...', { window: Rollup.indexWindow.sliding(Rollup.span.weeks(6)) });

type IndexingState =
  | { type: 'notConfigured' }
  | { type: 'needsPhotoAccess' }
  | { type: 'downloadingAssets'; fraction: number }
  | { type: 'indexing'; indexed: number; total: number; searchable: boolean }
  | { type: 'ready'; photos: number; updatedAt: string }
  | { type: 'failed'; error: RollupErrorBody };

type PhotoAccess = 'authorized' | 'limited' | 'denied' | 'restricted' | 'notDetermined';

type IndexOptionsInput = {
  window?: IndexWindow;
  mediaTypes?: MediaType[];
  focus?: Focus;
  places?: boolean;
  screenshotEntities?: boolean;
  allowsCellular?: boolean;
  updatesAutomatically?: boolean;
  maxPhotos?: number | null;
  backgroundProgress?: { title?: string; subtitle?: string };
};

type IndexOptions = {
  window: IndexWindow;
  mediaTypes: MediaType[];
  focus: Focus;
  places: boolean;
  screenshotEntities: boolean;
  allowsCellular: boolean;
  updatesAutomatically: boolean;
  maxPhotos?: number;
  backgroundProgress: { title: string; subtitle?: string };
};

type IndexWindow = { type: 'growing'; span: Span } | { type: 'sliding'; span: Span };
type Span = { unit: 'days' | 'weeks' | 'months' | 'years'; value: number };
type MediaType = 'photos' | 'screenshots' | 'videos';
type Focus = 'everything' | 'food';

type SearchResults = {
  query: string;
  results: SearchResult[];
  plan: SearchPlan;
  seconds: number;
  timings: Record<string, number>;
  coverage?: JSONValue;
};

type SearchResult = {
  id: string;                 // PhotoKit local identifier
  relevance?: number;
  matchedText?: string;
  date?: string;              // when it was taken
  timeZone?: { identifier: string };
  mediaType: 'photo' | 'video' | 'screenshot';
  isFavorite: boolean;
  location?: SearchLocation;
  labels: SearchLabel[];
  places: SearchPlace[];
  cuisines: string[];
  text?: string;
  screenshot?: SearchScreenshot;
  score?: number;
  retrievalScore?: number;
  placeSimilarity?: number;
  matchReasons: string[];
  placeMatches?: JSONValue;
};

type SearchLocation = {
  neighborhood?: string;
  city?: string;
  metro?: string;
  country?: string;
  countryCode?: string;
  latitude?: number;
  longitude?: number;
};

type SearchLabel = { id: string; name: string; probability?: number; similarity?: number };
type SearchPlace = { name: string; category?: string; confidence: number };

type SearchScreenshot = {
  appKind: string;
  topic: string;
  action: string;
  confidence: Record<string, number>;
  sensitivity: string[];
  eventTime?: string;
  temporalRelation: string;
  entities: { id: number; type: string; value: string }[];
  entityStatus: string;
};

type SearchPlan = {
  operation: string;
  retrievalIntent: string;
  visualText: string;
  sort: string;
  details: JSONValue;
};

type Answer = {
  text: string;
  assetIdentifiers: string[];  // the photos the answer rests on
  declined: boolean;           // the question was not about the person's own life
};

type Profile<T = { [key: string]: JSONValue }> = {
  json: T;                            // the schema's shape, null where their life does not say
  evidence: Record<string, string[]>; // photos behind each filled field, by JSON Pointer
  refused: Record<string, string>;    // fields the server would not fill, with the reason
};

type JSONValue = null | boolean | number | string | JSONValue[] | { [key: string]: JSONValue };

class RollupError extends Error {
  readonly code: RollupErrorCode;
  readonly serverCode?: string;   // the server's own code, such as 'rate_limited'
  readonly retryable?: boolean;   // whether the same call can succeed later unchanged
  readonly retryAfter?: number;   // seconds to wait before retrying, when the server said
  toJSON(): RollupErrorBody;
}

function isRollupError(error: unknown, code?: RollupErrorCode): error is RollupError;

type RollupErrorBody = {
  code: RollupErrorCode;
  message: string;
  serverCode?: string;
  retryable?: boolean;
  retryAfter?: number;
};

type RollupErrorCode =
  | 'simulatorUnsupported'
  | 'notConfigured'
  | 'missingRequirement'
  | 'photoAccessDenied'
  | 'noIndex'
  | 'assetsUnavailable'
  | 'network'
  | 'server'
  | 'indexing'
  | 'cancelled'
  | 'invalidSchema'
  | 'accessRevoked'
  | 'appPendingApproval'
  | 'quotaExceeded'
  | 'rateLimited'
  | 'appAttestFailed'
  | 'unknown'
  | 'unsupportedPlatform'   // not an iPhone: Android, the web, or the module is not linked
  | 'invalidOptions';       // index options the SDK can't read