JavaScript API

npm install @meantjs/profile@0.5.0 @meantjs/format@0.5.0 \
  @meantjs/consent@0.5.0 @meantjs/tools@0.5.0 @meantjs/reconcile@0.5.0

export const DEFAULT_SCHEMA_PATH: string;
export const DEFAULT_PACKS_DIR: string;
export function createSchemaValidator(schema?: string | Record<string, unknown>): Promise<SchemaValidator>;
export function loadPacks(dir?: string): Promise<Pack[]>;
export function runCli(argv: string[], io: { stdout: { write(text: string): unknown }; stderr: { write(text: string): unknown } }): Promise<0 | 1 | 2>;
export const USAGE: string;

export const LAYERS: readonly ["author", "third_party", "pack", "inferred"];
export function resolveService(opts: ResolveOptions): Promise<ResolveResult>;
export function validateProfile(doc: unknown, opts: { validateSchema: SchemaValidator; did?: string | null; didLabel?: string; resolved?: boolean }): Promise<ValidateResult>;
export function idlHash(label: string): number;
export function jcs(value: unknown): string;
export function profileId(doc: unknown): string;
export function parseAddress(at: string): Address | null;
export function parseRelPath(rel: string): { index: number | null; segs: PathSegment[] } | null;
export function compileInterface(source: string, label?: string): Promise<{ iface: Iface } | { failure: { code: string; message: string }[] }>;
export function interfaceFromEnvelope(envelope: unknown, label?: string): { iface: Iface } | { failure: { code: string; message: string }[] };
export function matchPack(canister: Iface, pack: unknown, opts?: Record<string, unknown>): Promise<{ matched: boolean; reasons: { at: string; message: string }[]; relaxed: unknown; fragment: Iface } | { error: { code: string; message: string }[] }>;
export function matchService(canister: Iface, fragment: Iface, opts?: Record<string, unknown>): { ok: boolean; reasons: { at: string; message: string }[]; relaxed: unknown };
export function typeSubtype(S: Iface, s: unknown, T: Iface, t: unknown, opts?: Record<string, unknown>): unknown;
export function positions(iface: Iface, methodName: string, side: "args" | "results", maxDepth?: number): Generator<Position>;
export function analyzeProfiles(iface: Iface, items: unknown[], opts?: { attribute?: boolean }): { diagnostics: Diagnostic[]; layered: LayeredTags; ordered: unknown[]; stale: Set<unknown> };
export function resolvedForm(iface: Iface, profiles: unknown[], tags: LayeredTags, diagnostics: Diagnostic[]): ResolvedForm;
export function buildTree(iface: Iface, methodName: string, side: "args" | "results", tags: LayeredTags): unknown;
export const DOC_ATTRIBUTES_VERSION: 1;
export function profileFromDocAttributes(
  response: unknown,
  opts?: { name?: string; origin?: "author" | "third_party"; language?: string; canisterId?: string },
): { ok: boolean; doc: ProfileDocument | null; diagnostics: DocDiagnostic[] };
export const SERVED_SECTION: "icp:public candid:profile";
export const SERVED_METADATA: "candid:profile";
export const SERVED_MAX_BYTES: number;
export function readServedProfile(
  bytes: Uint8Array,
  opts: { canisterId: string | null; label?: string },
): { ok: boolean; doc: ProfileDocument | null; diagnostics: Diagnostic[] };

export interface ProfileStatus {
  name: string;
  origin: string | null;
  kind: string | null;
  profile_id: string | null;
  status: "applied" | "rebound" | "stale" | "not_matched" | "invalid";
  explicit: boolean;
}
// …
export interface ResolveOptions {
  /** Candid source of the service (exactly one of `did`, `envelope` and `abi`). */
  did?: string;
  /** The service's candid-core ContractEnvelope. */
  envelope?: unknown;
  /** An EVM contract's ABI: human-readable fragments or JSON ABI entries (section 15). */
  abi?: readonly (string | Record<string, unknown>)[];
  didLabel?: string;
  /** Applied as given; a pack here must match. */
  profiles?: { doc: unknown; label?: string }[];
  /** Tried by Candid subtyping (an EVM pack by selector); applied only if they match. */
  packs?: { doc: unknown; label?: string }[];
  validateSchema: SchemaValidator;
}

export interface ResolveResult {
  ok: boolean;
  /** null when the service does not compile (or the envelope cannot be read). */
  resolved: ResolvedForm | null;
  diagnostics: Diagnostic[];
  profiles: ProfileStatus[];
}

import { createSchemaValidator, loadPacks, resolveService } from "@meantjs/profile";
import { readFileSync } from "node:fs";

const validateSchema = await createSchemaValidator();
const packs = (await loadPacks()).map(({ doc }) => ({ doc }));
const r = await resolveService({ did: readFileSync("ledger.did", "utf8"), validateSchema, packs });
for (const p of r.profiles) console.log(p.status, p.name, p.profile_id);

export interface PathSegment {
  kind: "field" | "elem";
  /** The field name, or `#<id>` for a numeric id. */
  label?: string;
  id?: number;
}

export type Address =
  | { kind: "type"; decl: string; segs: PathSegment[] }
  | { kind: "arg" | "result"; method: string; index: number; segs: PathSegment[] }
  | { kind: "method"; method: string; segs: [] };

/** The largest Candid field id. */
export const U32_MAX: 4294967295;
/** The Candid field-name hash. */
export function idlHash(label: string): number;
/** `.amount.e8s`, `.#5`, `[]` to segments; null when the path does not parse. */
export function parsePath(path: string): PathSegment[] | null;
/** `send(0).to`, `balance->(0)`, `type:Tokens.e8s` or a method name; null when the address does not parse. */
export function parseAddress(at: string): Address | null;
/** A path relative to a method: `(0).to.owner`, `to.owner` or `Ok`; `index` is null without `(n)`. */
export function parseRelPath(rel: string): { index: number | null; segs: PathSegment[] } | null;
/** The resolver's key of a method position. */
export function methodKey(method: string, side: "arg" | "res", index: number, segs: PathSegment[]): string;
/** The resolver's key of a `type:` edge. */
export function edgeKey(parent: { container: number; kind: string; id?: number }): string;

import { parseAddress, idlHash } from "@meantjs/profile/address";

const a = parseAddress("icrc1_transfer(0).amount");
if (a !== null && a.kind === "arg") console.log(a.method, a.index, a.segs.map((s) => s.label));
idlHash("amount"); // the u32 a Contract stores for the field

export const PROFILE_SCHEMA: Record<string, unknown>;
export const STANDARD_PACKS: readonly Pack[];
export function initCompiler(input?: BufferSource | URL | string | Response): Promise<void>;
export function createSchemaValidator(doc?: Record<string, unknown>): Promise<SchemaValidator>;
export function schemaDiagnostics(validateSchema: SchemaValidator): Diagnostic[];

export interface AbiFunction {
  name: string;
  inputs: AbiParam[];
  outputs: AbiParam[];
  stateMutability: "pure" | "view" | "nonpayable" | "payable";
  signature: string;
  typeSignature: string;
  selector: string;
  canonical: string;
  at?: string;
}
export type AbiValue = string | bigint | boolean | Uint8Array | AbiValue[] | { [key: string]: AbiValue };
export declare class AbiError extends Error {
export function keccak256(input: Uint8Array | string): Uint8Array;
export function keccak256Hex(input: Uint8Array | string): string;
export function jcs(value: unknown): string;
export const DEFAULT_ABI_LIMITS: Readonly<Required<AbiLimits>>;
export function parseAbi(entries: unknown, label?: string): { functions: AbiFunction[]; errors: { at: string; message: string }[] };
export function parseSignature(signature: string, where?: string): AbiFunction;
export function abiInterfaceId(functions: readonly AbiFunction[], types?: Eip712Types): string;
export function canonicalFragment(f: Pick<AbiFunction, "name" | "inputs" | "outputs" | "stateMutability">): string;
export function namedSignature(f: Pick<AbiFunction, "name" | "inputs">): string;
export function typeSignature(f: Pick<AbiFunction, "name" | "inputs">): string;
export function selectorOf(f: Pick<AbiFunction, "name" | "inputs">): string;
export function typeString(type: AbiType, names?: boolean): string;
export function componentKey(param: AbiParam, index: number): string;
export function encodeParams(params: readonly AbiParam[], values: Record<string, AbiValue>): Uint8Array;
export function encodeCall(f: AbiFunction, values: Record<string, AbiValue>): Uint8Array;
export function decodeParams(params: readonly AbiParam[], data: Uint8Array, limits?: AbiLimits): Record<string, AbiValue>;
export function toChecksumAddress(address: string): string;
export function readAddress(text: string): string;
export function typedDataDigest(typed: TypedData): string;
export type Eip712Types = Record<string, { name: string; type: string }[]>;
export function parseEip712Types(types: unknown, label?: string): { types: Eip712Types; errors: { at: string; message: string }[] };
export function encodeType(types: Eip712Types, primary: string): string;
export function eip712TypeHash(types: Eip712Types, primary: string): string;

import { eip712TypeHash, encodeType, parseEip712Types } from "@meantjs/profile/evm";

const { types, errors } = parseEip712Types({
  Mail: [
    { name: "from", type: "Person" },
    { name: "to", type: "Person" },
    { name: "contents", type: "string" },
  ],
  Person: [
    { name: "name", type: "string" },
    { name: "wallet", type: "address" },
  ],
});
errors; // []
encodeType(types, "Mail"); // "Mail(Person from,Person to,string contents)Person(string name,address wallet)"
eip712TypeHash(types, "Mail"); // "0xa0cedeb2dc280ba39b857546d74f5549c3a1d7bdc2dd96bf881f76108e23dac2"
parseEip712Types({ Short: [{ name: "x", type: "uint" }] }).errors;
// [{ at: "types.Short[0]", message: "write uint256, not uint: the type hash hashes the type as written" }]

import schema from "@meantjs/profile/schema.json" with { type: "json" };          // copy of spec/profile-v0.schema.json
import icrc1 from "@meantjs/profile/packs/icrc1.profile.json" with { type: "json" };
const validateSchema = await createSchemaValidator(schema);                            // a document, not a path
const r = await resolveService({ did, validateSchema, packs: [{ doc: icrc1 }] });

export type ValueTag = "amount" | "timestamp" | "duration" | "account" | "subaccount" | "bytes";
export type TimeUnit = "ns" | "us" | "ms" | "s";
export type BytesEncoding = "utf8" | "hex" | "base64";
export interface AmountOptions {
  decimals: number | bigint | string;
  symbol?: string;
  candid?: string;
  threshold?: string | bigint;
  message?: string;
}
export function parseAmount(input: string, options: AmountOptions): string;
export function displayAmount(value: string | bigint, options: AmountOptions): string;
export function convertUnit(value: string | bigint, from: TimeUnit, to: TimeUnit): string;
export function alignNow(nowNs: bigint, unit: TimeUnit): bigint;
export function parseTimestamp(input: string, options: { unit: TimeUnit; candid?: string; now?: bigint }): string;
export interface TimestampOptions {
  unit: TimeUnit;
  candid?: string;
  threshold?: string | bigint;
  message?: string;
  labels?: Record<string, string>;
}
export function displayTimestamp(value: string | bigint, options: TimestampOptions): string;
export function parseDuration(input: string, options: { unit: TimeUnit; candid?: string }): string;
export function displayDuration(value: string | bigint, options: { unit: TimeUnit; candid?: string }): string;
export function parseAccount(input: string): Account;
export function displayAccount(account: { owner: string | Uint8Array; subaccount?: ByteInput | null }): string;
export function principalFromText(text: string): Uint8Array;
export function principalToText(bytes: Uint8Array): string;
export function parseSubaccount(input: string): Uint8Array;
export function displaySubaccount(value: ByteInput): string;
export function parseBytes(input: string, options: { encoding: BytesEncoding; maxLen?: number }): Uint8Array;
export function displayBytes(value: ByteInput, options: { encoding: BytesEncoding }): string;
export function asUint8Array(value: unknown): Uint8Array | null;
export interface Formatter {
  readonly tag: ValueTag;
  readonly candid: string;
  readonly args: Readonly<Record<string, unknown>>;
  parse(input: string, context?: { now?: bigint }): ParsedValue;
  display(value: unknown): string;
  safeParse(input: string, context?: { now?: bigint }): SafeResult<ParsedValue>;
  safeDisplay(value: unknown): SafeResult<string>;
  describe(): Description;
}
export const VALUE_TAGS: readonly ValueTag[];
export function formatterFor(node: FormatNode, options?: { refs?: Record<string, unknown>; now?: bigint; token?: { decimals: number | bigint | string; symbol?: string } }): Formatter | null;
export function describeInput(tag: ValueTag, args: Readonly<Record<string, unknown>>, candid: string, options?: { accepts?: (input: string) => boolean }): Description;
export function normalizeName(text: string): string;
export function resolveName<V>(
  entries: NameEntry<V>[],
  input: string,
  opts?: { isValue?: (text: string) => boolean; kind?: (kind: unknown) => boolean; by?: "value" | "show" },
): NameResolution<V>;
export function ownerOf<V>(entries: NameEntry<V>[], value: unknown, opts?: { by?: "value" | "show" }): NameEntry<V> | undefined;
export function nameOf<V>(entries: NameEntry<V>[], value: V, opts?: { by?: "value" | "show"; show?: (value: unknown) => string }): string;

import { parseAmount, displayAmount, FormatError } from "@meantjs/format";

parseAmount("1.5 ICP", { decimals: 8, symbol: "ICP" }); // "150000000"
displayAmount("150000000", { decimals: 8, symbol: "ICP" }); // "1.5 ICP"
try {
  parseAmount("1.123456789", { decimals: 8 });
} catch (e) {
  if (e instanceof FormatError) console.log(e.code); // "E_EXCESS_PRECISION": never rounded
}

import { displayTimestamp, formatterFor } from "@meantjs/format";

const expiration = { unit: /** @type {const} */ ("s"), candid: "uint48", threshold: "281474976710655", message: "Never", labels: { "0": "Only in the block it is used" } };
displayTimestamp("0", expiration); // "Only in the block it is used"
displayTimestamp("281474976710655", expiration); // "Never"
displayTimestamp("1798761600", expiration); // "2027-01-01T00:00:00Z"

const amount = { abi: "uint160", tags: { amount: { args: { token: "details.token", threshold: "1461501637330902918203684832716283019655932542975" } } } };
const f = formatterFor(amount, { token: { decimals: 6, symbol: "USDC" } });
f?.display("1500000"); // "1.5 USDC"
f?.display("1461501637330902918203684832716283019655932542975"); // "Unlimited USDC"
// formatterFor(amount) without `token` throws E_REF_UNRESOLVED

export interface Icrc21Context {
  resolved: ResolvedForm;
  refs?: Record<string, unknown>;
  languagePolicy?: "fallback" | "error";
  rawArguments?: boolean;
  limits?: DecodeLimits;
}
export type Icrc21Result = Icrc21ConsentMessageResponse & { readonly diagnostics: ConsentDiagnostic[]; readonly provenance: Provenance };
export function icrc21ConsentMessage(request: Omit<Icrc21ConsentMessageRequest, "arg"> & { arg: Bytes }, context: Icrc21Context): Icrc21Result;
export function handleConsentRequest(requestBytes: Uint8Array, context: Icrc21Context): Uint8Array;
export function toIcrc21Error(error: unknown): Icrc21Error;
export const SUPPORTED_LANGUAGE: "en";
export function encodeConsentResponse(response: Icrc21ConsentMessageResponse): Uint8Array;
export function decodeConsentResponse(bytes: Uint8Array): Icrc21ConsentMessageResponse;
export function encodeConsentRequest(request: Icrc21ConsentMessageRequest): Uint8Array;
export function decodeConsentRequest(bytes: Uint8Array): Icrc21ConsentMessageRequest;
export function toJson(value: unknown): unknown;
export interface GenerateConsentInput {
  resolved: ResolvedForm;
  method: string;
  arg: Bytes;
  refs?: Record<string, unknown>;
  form?: "fields" | "generic";
  utcOffsetMinutes?: number | null;
  rawArguments?: boolean;
  limits?: DecodeLimits;
  canisterId?: string;
}
export function generateConsent(input: GenerateConsentInput): {
  form: "fields" | "generic";
  message: Icrc21ConsentMessage;
  zoneSensitive: boolean;
  values: unknown[];
  grant: Grant | null;
  diagnostics: ConsentDiagnostic[];
  provenance: Provenance;
  model: Model;
};
export function buildModel(input: { resolved: ResolvedForm; method: string; arg: Bytes; limits?: DecodeLimits }): Model;
export function decodeArguments(method: { args: unknown[] }, arg: Bytes, limits?: DecodeLimits): unknown[];
export function schemaFor(node: unknown, where?: string, depth?: number): unknown;
export function parseTemplate(template: string): TemplatePart[];
export function resolvePath(method: { args: unknown[] }, relpath: string): ResolvedPath | { error: string };
export function valuesAt(path: ResolvedPath, values: unknown[]): unknown[];
export declare class Renderer {
export function zoneName(offsetMinutes: number): string;
export function renderFields(model: Model, renderer: Renderer, options?: { rawArguments?: boolean }): { intent: string; fields: [string, Icrc21Value][] };
export function renderGeneric(model: Model, renderer: Renderer, options?: { rawArguments?: boolean; headingLevel?: number }): string;
export function codeSpan(s: string): string;
export function escapeMarkdown(s: string): string;
export function visible(s: string): string;
export declare class ConsentError extends Error {

import { icrc21ConsentMessage, handleConsentRequest } from "@meantjs/consent";

const response = icrc21ConsentMessage(
  {
    method: "icrc1_transfer",
    arg: argBytes, // Uint8Array: the Candid-encoded argument tuple of the call
    user_preferences: { metadata: { language: "en", utc_offset_minutes: 120 }, device_spec: { GenericDisplay: null } },
  },
  {
    resolved, // fixtures/*.resolved.json shape, or the output of `candid-profile resolve`
    refs: { "query:icrc1_decimals": 8, "query:icrc1_symbol": "TKA" }, // dynamic refs, resolved by the caller
  },
);

export interface Grant {
  kind: "transfer" | "approve";
  /** Who may take the tokens: an EIP-55 address, or an account in its ICRC-1 text. Exactly one of `spender` and `to`. */
  spender?: string;
  /** Who is paid directly: an EIP-55 address, or an account in its ICRC-1 text. */
  to?: string;
  /** The token: an EIP-55 address, or a canister id in its canonical text. */
  token: string;
  /** Base units as a decimal string; `null` when unlimited without a count (DAI's `allowed: true`). A grant of nothing is `"0"`. */
  amount: { units: string | null; unlimited: boolean };
  /** `at`: exact seconds since the Unix epoch as a decimal string, never rounded ("1767225600.123456789"). `now`: a transfer, made when it is sent. */
  ends: { at: string } | { never: true } | { now: true };
}

export type ValidatorResult = { Ok: string } | { Err: string };
export const SNS_RENDERING_RULES: "candid-profile-sns/v0";
export function snsValidatorRendering(input: {
  payload: Bytes;
  resolved: ResolvedForm;
  method: string;
  refs?: Record<string, unknown>;
  limits?: DecodeLimits;
}): ValidatorResult & { readonly diagnostics: ConsentDiagnostic[]; readonly provenance: Provenance };
export function handleSnsValidatorCall(payload: Uint8Array, context: { resolved: ResolvedForm; method: string; refs?: Record<string, unknown>; limits?: DecodeLimits }): Uint8Array;
export function encodeValidatorResult(result: ValidatorResult): Uint8Array;
export function decodeValidatorResult(bytes: Uint8Array): ValidatorResult;
export function parseGovernanceRendering(text: string): GovernanceRendering | null;
export function verifySnsRendering(input: {
  payloadTextRendering: string;
  payload: Bytes;
  resolved: ResolvedForm;
  targetCanisterId: string;
  method: string;
  refs?: Record<string, unknown>;
  limits?: DecodeLimits;
}): { ok: boolean; checks: SnsCheck[]; expectedRendering: string | null; parsed: GovernanceRendering | null };

export type EvmResolvedForm = ResolvedForm & { chain: "evm" };
export function decodeCalldata(resolved: ResolvedForm, calldata: Uint8Array | string, limits?: AbiLimits): { method: string; selector: string; values: Record<string, AbiValue> };
export interface EvmConsentInput {
  resolved: ResolvedForm;
  calldata: Uint8Array | string;
  to: string;
  chainId?: number | bigint | string;
  refs?: Record<string, unknown>;
  tokens?: Record<string, { decimals: number | bigint | string; symbol?: string }>;
  form?: "generic" | "fields";
  utcOffsetMinutes?: number | null;
  rawArguments?: boolean;
  limits?: AbiLimits;
}
export function evmConsent(input: EvmConsentInput): {
  form: "generic" | "fields";
  message: string | { intent: string; fields: [string, string][] };
  method: string;
  selector: string;
  to: string;
  chainId: string | null;
  /** The decoded arguments by parameter name, as `decodeCalldata` gives them. */
  values: Record<string, AbiValue>;
  /** What the call grants (its token is the contract called, unless the amount's tag names a field), or null; a W_GRANT diagnostic says why one cannot be read. */
  grant: Grant | null;
  diagnostics: ConsentDiagnostic[];
  provenance: Provenance;
  model: Model;
};
export interface TypedData {
  types: Record<string, { name: string; type: string }[]>;
  primaryType: string;
  domain: { name?: string; version?: string; chainId?: number | bigint | string; verifyingContract?: string; salt?: string };
  message: Record<string, unknown>;
}
export interface Eip712ConsentInput {
  resolved: ResolvedForm;
  typedData: TypedData;
  chainId: number | bigint | string;
  refs?: Record<string, unknown>;
  tokens?: Record<string, { decimals: number | bigint | string; symbol?: string }>;
  form?: "generic" | "fields";
  utcOffsetMinutes?: number | null;
  rawArguments?: boolean;
  limits?: { maxBytes?: number; maxElements?: number };
}
export function eip712Consent(input: Eip712ConsentInput): {
  form: "generic" | "fields";
  message: string | { intent: string; fields: [string, string][] };
  primaryType: string;
  typeHash: string;
  digest: string;
  verifyingContract: string;
  chainId: string;
  /** The message's values by member name, as read from the typed data: integers as decimal strings, addresses in EIP-55 form. */
  values: Record<string, AbiValue>;
  /** What the signature grants (its token is the verifying contract, unless the amount's tag names a member), or null; a W_GRANT diagnostic says why one cannot be read. */
  grant: Grant | null;
  diagnostics: ConsentDiagnostic[];
  provenance: Provenance;
  model: Model;
};

import { createSchemaValidator, loadPacks, validateProfile } from "@meantjs/profile";
import { eip712Consent } from "@meantjs/consent/evm";

const validateSchema = await createSchemaValidator();
const erc2612 = (await loadPacks()).find((p) => p.doc.name === "erc2612");
const v = erc2612 && (await validateProfile(erc2612.doc, { validateSchema, resolved: true }));
if (!v?.resolved) throw new Error("the EIP-2612 pack did not resolve");

const r = eip712Consent({
  resolved: v.resolved,
  typedData: {
    types: {
      Permit: [
        { name: "owner", type: "address" },
        { name: "spender", type: "address" },
        { name: "value", type: "uint256" },
        { name: "nonce", type: "uint256" },
        { name: "deadline", type: "uint256" },
      ],
    },
    primaryType: "Permit",
    domain: { name: "Token A", version: "1", chainId: 31337, verifyingContract: "0x5FbDB2315678afecb367f032d93F642f64180aa3" },
    message: {
      owner: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
      spender: "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
      value: "1500000000000000000",
      nonce: 0,
      deadline: "115792089237316195423570985008687907853269984665640564039457584007913129639935",
    },
  },
  chainId: 31337,
  refs: { "query:decimals": 18, "query:symbol": "TKA" },
});
r.typeHash; // "0x6e71edae12b1b97f4d1f60370fef10105fa2faae0126114a169c64845d6126c9": EIP-2612's Permit
r.message; // "# Permit token spending\n\nAllow `0x3C44…93BC` to spend up to `1.5 TKA` from `0x7099…79C8`. Signature expires: `Never`. …"
r.grant; // { kind: "approve", spender: "0x3C44…93BC", token: "0x5FbD…0aa3", amount: { units: "1500000000000000000", unlimited: false }, ends: { never: true } }

export const ERC7730_SCHEMA_URL: "https://eips.ethereum.org/assets/eip-7730/erc7730-v2.1.0.schema.json";
export const ERC8176_SCHEMA_UID: "0xe023eef113c1670774801c34b377fdf612dd8a4d2fa92fe382e15bd91fafb5c2";
export const EAS_ADDRESS: "0xA1207F3BBa224E2c9c3c6D5aF63D0eb1582Ce587";
export interface Erc7730FieldGroup {
  path: string;
  fields: (Erc7730Field | Erc7730FieldGroup)[];
}
export interface Erc7730Options {
  context?: "contract" | "eip712";
  deployments?: Erc7730Deployment[];
  owner?: string;
  contractName?: string;
  info?: { url: string; deploymentDate?: string };
  token?: { name: string };
}
export function erc7730Descriptor(resolved: ResolvedForm, options?: Erc7730Options): { descriptor: Erc7730Descriptor; descriptorHash: string; notes: string[] };
export function descriptorHash(descriptor: object): string;
export interface Erc8176Input {
  descriptorHash: string;
  time: bigint | number | string;
  expirationTime: bigint | number | string;
  salt: string;
  refUID?: string;
}
export function erc8176Attestation(input: Erc8176Input): { typedData: Erc8176TypedData; digest: string };

import type { Grant } from "./index.mjs";

/** A term the agent wrote that cannot be read, or a step out of order: `message` is written for the agent. */
export declare class TermsError extends Error {
  constructor(code: string, message: string);
  readonly code: TermsCode;
}
export declare const TERMS_CODES: {
  /** A field is missing or empty, or both spender and to are given. */
  readonly MISSING: "E_TERMS_MISSING";
  /** A token the wallet does not know. */
  readonly TOKEN: "E_TERMS_TOKEN";
  /** An app the wallet does not know, or an address or account that is not one. */
  readonly PARTY: "E_TERMS_PARTY";
  /** An amount that cannot be read, or has more decimals than its token: never rounded. */
  readonly AMOUNT: "E_TERMS_AMOUNT";
  /** An end that cannot be read, or a date before today. */
  readonly END: "E_TERMS_END";
  /** termsGate: a step out of order. */
  readonly ORDER: "E_TERMS_ORDER";
};
export type TermsCode = (typeof TERMS_CODES)[keyof typeof TERMS_CODES];

/** What the terms functions read from the wallet. Pure: the wallet's clock and zone come in here. */
export interface Wallet {
  /** The tokens it knows, by symbol: an EVM token's address or a ledger's canister id, and its decimals. */
  tokens: Record<string, { address: string; decimals: number } | { canister: string; decimals: number }>;
  /** The apps and people it knows by name: an address, or an account in its ICRC-1 text. */
  apps?: Record<string, string>;
  /** Nanoseconds since the Unix epoch. */
  now: bigint;
  /** The user's zone (default 0, UTC): a date allows its whole day there. */
  utcOffsetMinutes?: number;
}

/** The terms as the agent writes them, a tool's arguments: `spender` or `to`, exactly one. */
export interface TermsFields {
  /** The token, by the symbol the wallet knows. */
  token: string;
  /** Who may spend the tokens: an app's name as the wallet knows it, or an address or account the user gave. */
  spender?: string;
  /** Who is paid directly: a name the wallet knows, or an address or account the user gave. */
  to?: string;
  /** The most, in tokens ("100", "0.5", "100 USDC"), or "unlimited". */
  max_amount: string;
  /** YYYY-MM-DD (the whole day counts), a length from today ("30 days", "2 weeks", "1 month", "1 year"), hours from now ("2 hours", an exact time), or "never". */
  expires_by: string;
}

/** What the user allows for one task, in the wallet's own values: `spender` or `to`, exactly one. */
export interface Terms {
  /** The token: an EIP-55 address, or a canister id in its canonical text. */
  token: string;
  symbol: string;
  decimals: number;
  spender?: string;
  to?: string;
  /** The app's name in the wallet's list, or null. */
  name: string | null;
  /** The most, in base units as a decimal string; `null` when unlimited. */
  amount: { units: string; unlimited: false } | { units: null; unlimited: true };
  /** `at`: the latest end, exact seconds since the Unix epoch as a decimal string; `day`: the local date whose whole day counts. */
  ends: { at: string; day?: string } | { never: true };
  utcOffsetMinutes: number;
  /** The fields as the agent wrote them, trimmed. */
  written: Record<string, string>;
}
/** Terms the user confirmed: `id` is the SHA-256 of their canonical JSON (RFC 8785), lowercase hex. */
export type ConfirmedTerms = Readonly<Terms & { id: string }>;

/** Reads the agent's terms. Throws TermsError when a term cannot be read; it never guesses a token, an app, decimals or a date. */
export function readTerms(fields: TermsFields | Record<string, unknown>, wallet: Wallet): Terms;
/** The terms in words, exactly, for the user to confirm on the wallet's own screen. */
export function termsText(terms: Terms | ConfirmedTerms): string;
/** The terms once the user has confirmed exactly `termsText(terms)`: frozen, with their `id`. */
export function confirmTerms(terms: Terms): ConfirmedTerms;
/** Whether a request's grant fits confirmed terms, and if not, why, in words. A null grant is not covered by terms. */
export function checkGrant(confirmed: ConfirmedTerms, grant: Grant | null, wallet: Wallet): { fits: boolean; reasons: string[] };

/** The order of one task: propose, confirm on the wallet's screen, read, check. Steps out of order throw TermsError E_TERMS_ORDER. */
export interface TermsGate {
  readonly state: "open" | "proposed" | "confirmed" | "read";
  readonly proposed: Readonly<Terms> | null;
  readonly confirmed: ConfirmedTerms | null;
  /** The agent's draft; replaces an earlier one and its confirmation. Returns the text to show the user. Refused once the request was read. */
  propose(terms: Terms): string;
  /** The user confirmed `shown`, which must be exactly the draft's text. */
  confirm(shown: string): ConfirmedTerms;
  /** The user said no: the draft is dropped. */
  reject(): void;
  /** Before the agent reads the request: refused until the user has confirmed terms. */
  read(): void;
  /**
   * The grant of the request read. `requestId` names the request the wallet will sign or send: eip712Consent's `digest`,
   * or for a call the wallet's own id of it. The terms cover one request, the first checked: another is refused, even
   * one that grants the same.
   */
  check(grant: Grant | null, wallet: Wallet, requestId: string): { fits: boolean; reasons: string[] };
}
export function termsGate(): TermsGate;

import { checkGrant, confirmTerms, readTerms, termsGate, termsText } from "@meantjs/consent/terms";

const wallet = {
  tokens: { TKA: { address: "0x5FbDB2315678afecb367f032d93F642f64180aa3", decimals: 18 } },
  apps: { Bob: "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" },
  now: 1_793_620_800_000_000_000n, // 2026-11-02T12:00:00Z, in nanoseconds
};
const month = readTerms({ token: "TKA", spender: "Bob", max_amount: "2", expires_by: "30 days" }, wallet);
termsText(month); // "Bob (0x3C44…93BC) may spend at most 2 TKA, until the end of 2 December 2026 (UTC)."
checkGrant(confirmTerms(month), r.grant, wallet);
// { fits: false, reasons: ["the permission never ends, the terms say until the end of 2 December 2026 (UTC)"] }

const gate = termsGate();
const shown = gate.propose(readTerms({ token: "TKA", spender: "Bob", max_amount: "2", expires_by: "never" }, wallet));
// "Bob (0x3C44…93BC) may spend at most 2 TKA, and this permission never ends."
gate.confirm(shown); // the person confirmed exactly `shown` on the wallet's own screen
gate.read(); // in a wallet, the agent reads the request only after this
gate.check(r.grant, wallet, r.digest); // { fits: true, reasons: [] }

export const COMMIT_TOOL: "commit";
export function prepareToolName(method: string): string;
export function caseToolName(method: string, label: string, read: boolean): string;
export function resolvedMethods(resolved: ResolvedForm | ResolvedForm[]): [string, unknown][];
export function buildToolPlans(resolved: ResolvedForm | ResolvedForm[]): { plans: Map<string, ToolPlan>; skipped: { method: string; reason: string }[] };
export function toolDefinitions(resolved: ResolvedForm | ResolvedForm[], options?: { canisters?: Canister[] }): ToolDefinition[];
export function readToolInput(
  plan: ToolPlan,
  input: unknown,
  context?: { refs?: Record<string, unknown>; now?: bigint; names?: Record<string, NameEntry[]> },
): { value: unknown; identity: [string, unknown][] } | { issues: InputIssue[] };
export function toCandid(node: unknown, value: unknown): unknown;
export function displayValue(node: unknown, value: unknown, refs?: Record<string, unknown>, names?: Record<string, NameEntry[]>): unknown;
export function nameEntries(resolved: unknown, set: string, reply: unknown): NameEntry[] | undefined;
export function classifyReply(plan: ToolPlan, reply: unknown): { cls: string; path: string[]; node: unknown; value: unknown };
export type CallResult =
  | { status: "replied"; reply: unknown }
  | { status: "rejected"; reject_code: number; message: string }
  | { status: "unknown"; message: string };
export type Outcome =
  | "declined"
  | "success"
  | "already_done"
  | "retry_same"
  | "retry_new"
  | "fix_input"
  | "fail"
  | "not_executed"
  | "unknown"
  | "reconcile";
export interface ToolLayerConfig {
  resolved: ResolvedForm | ResolvedForm[];
  canisters: Canister[];
  encode(method: string, value: unknown, args: unknown[]): Uint8Array | Promise<Uint8Array>;
  call(req: { canister: string; method: string; mode: string; arg: Uint8Array; value: unknown; args: unknown[] }): Promise<CallResult>;
  now(o: { canister: string }): Promise<bigint>;
  confirm?(preview: Preview): Promise<boolean | { approved: boolean }>;
  reconcile?(o: { canister: string; method: string; value: unknown; stamp: bigint; preview: Preview }): Promise<ReconcileFinding>;
}
export interface ToolLayer {
  listTools(): ToolDefinition[];
  skipped: { method: string; reason: string }[];
  callTool(name: string, input: unknown): Promise<ToolResult>;
}
export function createToolLayer(config: ToolLayerConfig): ToolLayer;

export const DEDUP_WINDOW_NS: bigint;
export const U64_MAX: bigint;
export const METHODS: readonly ["icrc1_transfer", "icrc2_approve", "icrc2_transfer_from"];
export function expectedTransaction(
  method: string,
  arg: Record<string, unknown>,
  caller: string,
  options?: { minting?: Account | null },
): ExpectedTransaction | undefined;
export function blockMatches(block: Icrc3Value, expected: ExpectedTransaction | undefined): boolean;
export interface MatchOptions {
  logLength: bigint;
  floor?: bigint;
  inFlight: boolean;
  stampExpired?: boolean;
  ledgerTime?: bigint;
  ledgerTimeAtLeast?: bigint;
  windowNs?: bigint;
  notOriginal?: bigint[];
}
export type MatchResult =
  | { status: "found"; block: bigint }
  | { status: "absent"; closedBy: "answered" | "too_old" | "window_passed"; clock?: ClockReading }
  | { status: "not_yet"; openUntil?: bigint; reason?: string; clock?: ClockReading }
  | { status: "unreadable"; reason: string; lookalike?: { block: bigint; op: string; capped: boolean } };
export function matchBlocks(blocks: { id: bigint; block: Icrc3Value }[], expected: ExpectedTransaction | undefined, options: MatchOptions): MatchResult;