superapp-miniapp-invoke-native 1.11.4 → 1.12.0

package/lib/main.d.ts

@@ -365,6 +365,34 @@ declare interface MiniAppParamsType {
     miniAppIds?: any[];
 }
 
+export declare interface MiniappSpanErrorInput {
+    type?: string;
+    message: string;
+    stack?: string;
+}
+
+export declare interface MiniappSpanEventInput {
+    name: string;
+    /** Unix epoch time in milliseconds. Must fall inside its span. */
+    time: number;
+    attributes?: OtelAttributes;
+}
+
+export declare interface MiniappSpanInput {
+    name: string;
+    kind: OtelSpanKind;
+    /** Unix epoch time in milliseconds. */
+    startTime: number;
+    /** Unix epoch time in milliseconds. Children must remain inside the parent interval. */
+    endTime: number;
+    status: OtelSpanStatus;
+    attributes?: OtelAttributes;
+    events?: MiniappSpanEventInput[];
+    error?: MiniappSpanErrorInput;
+    /** Child spans. The shell creates each child with this span as its OTel parent. */
+    children?: MiniappSpanInput[];
+}
+
 declare type MiniAppType = {
     miniApp: string;
     link?: never;
@@ -397,6 +425,7 @@ export declare class NativeApi {
     httpPlugin: HttpPlugins;
     printPlugins: PrintPlugins;
     downloadFilePlugin: DownloadFilePlugin;
+    otelPlugins: OtelPlugins;
 }
 
 declare interface NativeInfoConfigType {
@@ -421,6 +450,41 @@ declare interface NativeSendPrintParamsType {
     [key: string]: any;
 }
 
+export declare const OTEL_PLUGIN_PROTOCOL_VERSION: "1.0";
+
+export declare type OtelAttributes = Record<string, OtelAttributeValue>;
+
+export declare type OtelAttributeValue = string | number | boolean;
+
+declare class OtelPlugins implements OtelPluginsHandleType {
+    recordTrace(params: RecordOtelTraceParams): Promise<RecordOtelTraceResult>;
+    recordSpan(params: RecordOtelSpanParams): Promise<RecordOtelTraceResult>;
+    getStatus(): Promise<OtelPluginStatus>;
+}
+
+export declare interface OtelPluginsHandleType {
+    recordTrace(params: RecordOtelTraceParams): Promise<RecordOtelTraceResult>;
+    recordSpan(params: RecordOtelSpanParams): Promise<RecordOtelTraceResult>;
+    getStatus(): Promise<OtelPluginStatus>;
+}
+
+export declare interface OtelPluginStatus {
+    recordTrace: boolean;
+    recordSpan: boolean;
+    protocolVersion: typeof OTEL_PLUGIN_PROTOCOL_VERSION;
+    maxSpansPerTrace: number;
+    maxDepth: number;
+    maxAttributesPerSpan: number;
+    maxEventsPerSpan: number;
+    maxPayloadBytes: number;
+}
+
+export declare type OtelRecordCode = "OK" | "UNSUPPORTED" | "DISABLED" | "INVALID_PARAMETERS" | "INVALID_TREE" | "RATE_LIMITED" | "INTERNAL_ERROR";
+
+export declare type OtelSpanKind = "internal" | "client";
+
+export declare type OtelSpanStatus = "unset" | "ok" | "error";
+
 declare type PackOrdersScanBoxType = "pack_orders_scan_box" | "collect_orders_scan_box";
 
 declare class PaymentPlugins implements PaymentPluginsHandleType {
@@ -493,6 +557,34 @@ export declare interface ProcessParamsType {
     [key: string]: any;
 }
 
+export declare interface RecordedSpanIdentity {
+    name: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    children?: RecordedSpanIdentity[];
+}
+
+export declare type RecordOtelSpanParams = Omit<MiniappSpanInput, "children">;
+
+export declare interface RecordOtelTraceParams {
+    /** A nested span tree. The shell creates all real traceId/spanId values. */
+    span: MiniappSpanInput;
+}
+
+export declare interface RecordOtelTraceResult {
+    /** True means the shell accepted and ended the spans; export remains asynchronous. */
+    accepted: boolean;
+    code: OtelRecordCode;
+    protocolVersion: typeof OTEL_PLUGIN_PROTOCOL_VERSION;
+    sampled?: boolean;
+    /** Generated by the shell OTel provider. Miniapps must not provide this value. */
+    traceId?: string;
+    rootSpanId?: string;
+    /** Generated ID tree matching the submitted span/children structure. */
+    span?: RecordedSpanIdentity;
+}
+
 declare interface RedirectType {
     miniApp: string;
     params: any;