Types¶

Every type alias and interface exported from rosetta-frida. All are re-exported from the package root and also from rosetta-frida/types for callers that want to type-only-import.

import type {
    RosettaMap,
    Session,
    Resolver,
    ClassProxy,
    DiagnosticEvent,
    // ...
} from 'rosetta-frida';

Map types¶

Defined in src/types/map.ts.

`RosettaMap`¶

interface RosettaMap {
    schema_version: 5;
    app: string;
    version: string; // versionName label — fuzzy fallback only
    version_code: number; // authoritative selection key
    captured_at?: string; // ISO YYYY-MM-DD
    signer_sha256?: string | string[]; // signing-cert hash guard (match-any)
    generated_from?: GeneratedFrom; // signatures-revision provenance pointer
    status?: MapStatus; // lifecycle: active (default) / superseded / retracted
    superseded_by?: number; // version_code of the replacement map
    client_hints?: ClientHints; // per-client metadata (frida version range)
    sources?: MapSource[];
    classes: ClassMap;
}

interface ClientHints {
    frida_min_version?: string;
    frida_max_version?: string;
}

The top-level mapping file. See Map format reference for field semantics.

`RosettaMapRegistry`¶

type RosettaMapRegistry = Record<string, RosettaMap>;

Multi-version registry — a record keyed by version string. Used in multi-version bundles (recipe).

`MapSource`¶

interface MapSource {
    tool: string;
    config?: string;
    classes?: number;
}

Provenance entry. One per upstream tool / authoring pass.

`GeneratedFrom`¶

interface GeneratedFrom {
    signatures_rev: string; // 7–40-char git commit hash
}

Optional provenance pointer back to the signatures revision a map was generated from (#36). Required-if-present.

`MapStatus`¶

type MapStatus = 'active' | 'superseded' | 'retracted';

Lifecycle status of a map (#40). Absent ⇒ active. A superseded map still loads but rosetta.session(...) emits a map-status warning; a retracted map is refused fail-closed (MapRetractedError).

`ClassKind`¶

type ClassKind = 'class' | 'interface' | 'enum' | 'synthetic' | 'anonymous';

What kind of class an entry describes. Drives V2+ runtime discovery strategies (e.g. synthetic and anonymous classes are skipped).

`ClassEntry`¶

interface ClassEntry {
    obfuscated: string;
    extends?: string;
    kind?: ClassKind;
    dex?: string;
    methods?: MethodMap;
    fields?: FieldMap;
    source?: string;
}

`ClassMap`¶

type ClassMap = Record<string, ClassEntry>;

Keyed by real fully-qualified class name.

`MethodEntry`¶

interface MethodEntry {
    obfuscated: string;
    signature: string;
    static?: boolean;
    synthetic?: boolean;
    is_constructor?: boolean;
}

`MethodMap`¶

type MethodMap = Record<string, MethodEntry | MethodEntry[]>;

Methods keyed by real name. Single-overload form uses MethodEntry; multi-overload form uses MethodEntry[].

`FieldEntry`¶

interface FieldEntry {
    obfuscated: string;
    type: string;
    static?: boolean;
}

`FieldMap`¶

type FieldMap = Record<string, FieldEntry>;

Keyed by real field name.

Session types¶

Defined in src/types/session.ts.

`Session`¶

interface Session {
    readonly map: RosettaMap;
    readonly app: string;
    readonly version: string;
    readonly failurePolicy: FailurePolicy;
    readonly healthy: boolean;
}

The handle returned from rosetta.session(...). Read-only — switch sessions by calling rosetta.session(...) again rather than mutating this.

`SessionOptions`¶

interface SessionOptions {
    map: RosettaMap | RosettaMapRegistry;
    app?: string;
    version?: string;
    versionCode?: number; // authoritative selection key; auto-detected if omitted
    failurePolicy?: FailurePolicy;
    versionMatch?: VersionMatch;
    config?: RosettaConfig; // supplies the versionMatch default when omitted
    trace?: boolean;
    healthCheckThreshold?: number;
    skipHealthCheck?: boolean;
    enforceSigner?: boolean; // default true — fail closed on signer_sha256 mismatch
}

The options bag for rosetta.session(...) / createSession(...). See Session API for field semantics.

`FailurePolicy`¶

type FailurePolicy = 'strict' | 'warn';

How the Resolver responds to a missed lookup. See Concepts — failure policy.

`VersionMatch`¶

type VersionMatch = 'exact' | 'fuzzy' | VersionMatchConfig;

interface VersionMatchConfig {
    strategy?: 'exact' | 'fuzzy'; // default 'exact'
    versionCodeRange?: { min?: number; max?: number }; // opt-in numeric range over version_code
    versionRange?: { min?: string; max?: string }; // opt-in semver-ish range over the label
    maxDistance?: number | null; // default null — label-distance ceiling ([Δmaj,Δmin,Δpatch] <= [maxDistance,0,0])
    ranked?: boolean; // default false — expose ranked candidates
}

How strictly registry version matching behaves. The string forms are shorthand for the object form with all opt-in knobs at their legacy-preserving defaults; exact version_code always wins and a miss with fuzzy off still fails loudly. Each of strategy: 'fuzzy', versionCodeRange, and versionRange is an independent opt-in (a range engages even under strategy: 'exact'). maxDistance is a label-distance ceiling that applies to the nearest-label and versionRange tiers but not to versionCodeRange; the parser rejects an inverted range, an all-undefined range, and maxDistance paired with only a versionCodeRange. See Session API — versionMatch and Multi-version bundles.

The same shape is the typed config's versionMatching policy (RosettaConfig), validated by the one shared Zod schema.

Resolver types¶

Defined in src/types/resolver.ts.

`Resolver`¶

interface Resolver {
    resolveClass(realName: string): ResolvedClass;
    resolveMethod(
        className: string,
        methodName: string,
        argTypes?: readonly string[],
    ): ResolvedMethod;
    resolveField(className: string, fieldName: string): ResolvedField;
    translateType(typeName: string): string;
    invalidate(realName: string): void;
    override(realName: string, entry: ClassEntry): void;
    lookupField(className: string, fieldName: string): FieldEntry | undefined;
}

The core abstraction. Implementations cache per-session, look up via the map, and throw ResolveError on miss in strict mode.

The concrete implementation is ResolverImpl; build one via createResolver(map, { events, failurePolicy }). Most users go through rosetta.session(...) and don't construct a Resolver directly.

`ResolvedClass`¶

interface ResolvedClass {
    realName: string;
    obfName: string;
    entry: ClassEntry;
}

`ResolvedMethod`¶

interface ResolvedMethod {
    realName: string;
    obfName: string;
    className: string;       // obfuscated short class name
    signature: string;
    aidlTxn?: number;
    static: boolean;
    allOverloads: MethodEntry[];
}

`ResolvedField`¶

interface ResolvedField {
    realName: string;
    obfName: string;
    className: string;       // obfuscated short class name
    type: string;
    static: boolean;
}

Proxy types¶

Defined in src/types/proxy.ts. The contract for what rosetta.use(...) returns.

`ClassProxy`¶

interface ClassProxy {
    readonly $realName: string;
    readonly $obfName: string;
    readonly $native: unknown;
    readonly $resolver: Resolver;
    $new(...args: unknown[]): unknown;
    [member: string]: unknown;
}

`MethodHandle`¶

interface MethodHandle {
    overload(...argTypes: readonly string[]): OverloadHandle;
    readonly overloads: readonly OverloadHandle[];
    implementation: ((...args: unknown[]) => unknown) | null;
    readonly $native: unknown;
}

`OverloadHandle`¶

interface OverloadHandle {
    readonly argumentTypes: readonly { className: string }[];
    readonly returnType: { className: string };
    implementation: ((...args: unknown[]) => unknown) | null;
}

`FieldAccessor`¶

interface FieldAccessor<T = unknown> {
    value: T;
}

`InstanceProxy`¶

interface InstanceProxy {
    readonly $realName: string;
    readonly $obfName: string;
    readonly $native: unknown;
    [member: string]: unknown;
}

Returned from ClassProxy.$new(...) and from internal paths that wrap an instance for field translation.

Tier-1 API types¶

Defined in src/api/.

`HookHandle`¶

interface HookHandle {
    detach(): void;
    readonly detached: boolean;
}

`HookTarget`¶

interface HookTarget {
    readonly class: string;
    readonly method: string;
    readonly args: readonly string[];
}

`HookImpl`¶

type HookImpl = (this: unknown, ...args: unknown[]) => unknown;

`HookOptions`¶

interface HookOptions {
    readonly resolver: Resolver;
}

For the explicit-resolver form hook(target, impl, { resolver }). The ambient form rosetta.hook(target, impl) doesn't take options — it reads from the current session.

`FieldOptions`¶

interface FieldOptions {
    readonly resolver: Resolver;
}

Tier-2 API types¶

`UseOptions`¶

interface UseOptions extends ClassProxyOptions {
    resolver: Resolver;
}

`TypeOptions`¶

interface TypeOptions {
    resolver: Resolver;
}

Tier-3 API types¶

`MapApi`¶

interface MapApi {
    resolveClass(realName: string): ResolvedClass;
    resolveMethod(
        className: string,
        methodName: string,
        argTypes?: readonly string[],
    ): ResolvedMethod;
    resolveField(className: string, fieldName: string): ResolvedField;
    override(realName: string, entry: ClassEntry): void;
    extract(): RosettaMap;
}

The Tier 3 rosetta.map surface — see Tier 3 — rosetta.map.

`EventsApi`¶

interface EventsApi {
    on(listener: EventListener): () => void;
    onType<T extends DiagnosticEvent['type']>(
        type: T,
        listener: EventListener<Extract<DiagnosticEvent, { type: T }>>,
    ): () => void;
}

The Tier 3 rosetta.events surface — see Tier 3 — rosetta.events.

Diagnostic event types¶

Defined in src/types/events.ts. See Events reference for each event's semantics.

`DiagnosticEvent`¶

type DiagnosticEvent =
    | ResolveEvent
    | HealthCheckEvent
    | DetectEvent
    | MapLoadEvent
    | SignerCheckEvent;

Tagged union over the five event kinds.

`ResolveEvent`¶

interface ResolveEvent {
    type: 'resolve';
    name: string;
    obfName?: string;
    source: 'cache' | 'map' | 'override';
    miss?: boolean;
    classScope?: string;
    overloadSignature?: string;
}

`HealthCheckEvent`¶

interface HealthCheckEvent {
    type: 'health-check';
    passed: boolean;
    rate: number;
    failedEntries: readonly string[];
    threshold: number;
}

`DetectEvent`¶

interface DetectEvent {
    type: 'detect';
    app: string;
    version: string;
    source: 'auto' | 'override';
}

`MapLoadEvent`¶

interface MapLoadEvent {
    type: 'map-load';
    app: string;
    version: string;
    classCount: number;
    schemaVersion: number;
    selectionKind: 'exact' | 'nearest' | 'code-range' | 'label-range';
}

selectionKind records which tier picked the map, so a deliberate range pick is distinguishable from a nearest-label guess (not a single fuzzy bit). See Events reference.

`SignerCheckEvent`¶

interface SignerCheckEvent {
    type: 'signer-check';
    passed: boolean;
    app: string;
    expected: string;
    actual: readonly string[];
    source: 'signingInfo' | 'signatures';
}

Emitted only when the map carries a signer_sha256 and enforcement is on. See Events reference.

`EventListener`¶

type EventListener<E extends DiagnosticEvent = DiagnosticEvent> = (event: E) => void;

Types¶

Map types¶

RosettaMap¶

RosettaMapRegistry¶

MapSource¶

GeneratedFrom¶

MapStatus¶

ClassKind¶

ClassEntry¶

ClassMap¶

MethodEntry¶

MethodMap¶

FieldEntry¶

FieldMap¶

Session types¶

Session¶

SessionOptions¶

FailurePolicy¶

VersionMatch¶

Resolver types¶

Resolver¶

ResolvedClass¶

ResolvedMethod¶

ResolvedField¶

Proxy types¶

ClassProxy¶

MethodHandle¶

OverloadHandle¶

FieldAccessor¶

InstanceProxy¶