vident-sdk 0.11.0

package/dist/sampler.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Sampler abstraction for trace sampling decisions.
+ * Follows OpenTelemetry Sampler specification patterns.
+ *
+ * @see https://opentelemetry.io/docs/specs/otel/trace/sdk/#sampler
+ */
+export type SamplingDecision = "RECORD_AND_SAMPLE" | "DROP";
+export type ParentContext = {
+    traceId: string;
+    spanId: string;
+    /** Whether parent came from a remote service (traceparent header) */
+    isRemote: boolean;
+    /** Parent's sampling decision (from traceparent flags or local span) */
+    sampled: boolean;
+};
+export type SamplingContext = {
+    traceId: string;
+    name: string;
+    parentContext?: ParentContext;
+};
+export type Sampler = {
+    shouldSample(context: SamplingContext): SamplingDecision;
+    readonly description: string;
+};
+/**
+ * Always samples - use for development or when you want 100% traces.
+ */
+export declare function alwaysOnSampler(): Sampler;
+/**
+ * Never samples - use to disable tracing entirely.
+ */
+export declare function alwaysOffSampler(): Sampler;
+/**
+ * Samples based on a probability ratio (0.0 to 1.0).
+ * Uses Math.random() for simplicity - not deterministic across services.
+ */
+export declare function traceIdRatioSampler(ratio: number): Sampler;
+export type ParentBasedSamplerOptions = {
+    /** Sampler for new traces (no parent) */
+    root: Sampler;
+    /** Sampler when remote parent was sampled (default: AlwaysOn) */
+    remoteParentSampled?: Sampler;
+    /** Sampler when remote parent was not sampled (default: AlwaysOff) */
+    remoteParentNotSampled?: Sampler;
+    /** Sampler when local parent was sampled (default: AlwaysOn) */
+    localParentSampled?: Sampler;
+    /** Sampler when local parent was not sampled (default: AlwaysOff) */
+    localParentNotSampled?: Sampler;
+};
+/**
+ * Makes sampling decisions based on parent span's decision.
+ * This is the recommended default sampler for distributed tracing.
+ *
+ * - Remote parent sampled (traceparent with sampled=1): sample
+ * - Remote parent not sampled: don't sample
+ * - Local parent sampled: sample
+ * - Local parent not sampled: don't sample
+ * - No parent: delegate to root sampler
+ */
+export declare function parentBasedSampler(options: ParentBasedSamplerOptions): Sampler;
+//# sourceMappingURL=sampler.d.ts.map

package/dist/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../src/sampler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,GAAG,MAAM,CAAA;AAE3D,MAAM,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAA;IACjB,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,aAAa,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,OAAO,GAAG;IACrB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,gBAAgB,CAAA;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAKzC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAK1C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAW1D;AAED,MAAM,MAAM,yBAAyB,GAAG;IACvC,yCAAyC;IACzC,IAAI,EAAE,OAAO,CAAA;IACb,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,sEAAsE;IACtE,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,gEAAgE;IAChE,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,qEAAqE;IACrE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,yBAAyB,GAChC,OAAO,CAgCT"}

package/dist/sampler.js

@@ -0,0 +1,73 @@
+/**
+ * Sampler abstraction for trace sampling decisions.
+ * Follows OpenTelemetry Sampler specification patterns.
+ *
+ * @see https://opentelemetry.io/docs/specs/otel/trace/sdk/#sampler
+ */
+/**
+ * Always samples - use for development or when you want 100% traces.
+ */
+export function alwaysOnSampler() {
+    return {
+        shouldSample: () => "RECORD_AND_SAMPLE",
+        description: "AlwaysOnSampler",
+    };
+}
+/**
+ * Never samples - use to disable tracing entirely.
+ */
+export function alwaysOffSampler() {
+    return {
+        shouldSample: () => "DROP",
+        description: "AlwaysOffSampler",
+    };
+}
+/**
+ * Samples based on a probability ratio (0.0 to 1.0).
+ * Uses Math.random() for simplicity - not deterministic across services.
+ */
+export function traceIdRatioSampler(ratio) {
+    const normalizedRatio = Math.max(0, Math.min(1, ratio));
+    if (normalizedRatio === 0)
+        return alwaysOffSampler();
+    if (normalizedRatio === 1)
+        return alwaysOnSampler();
+    return {
+        shouldSample: () => Math.random() < normalizedRatio ? "RECORD_AND_SAMPLE" : "DROP",
+        description: `TraceIdRatioSampler{${normalizedRatio}}`,
+    };
+}
+/**
+ * Makes sampling decisions based on parent span's decision.
+ * This is the recommended default sampler for distributed tracing.
+ *
+ * - Remote parent sampled (traceparent with sampled=1): sample
+ * - Remote parent not sampled: don't sample
+ * - Local parent sampled: sample
+ * - Local parent not sampled: don't sample
+ * - No parent: delegate to root sampler
+ */
+export function parentBasedSampler(options) {
+    const { root, remoteParentSampled = alwaysOnSampler(), remoteParentNotSampled = alwaysOffSampler(), localParentSampled = alwaysOnSampler(), localParentNotSampled = alwaysOffSampler(), } = options;
+    return {
+        shouldSample: (context) => {
+            const { parentContext } = context;
+            // No parent - new trace, use root sampler
+            if (!parentContext) {
+                return root.shouldSample(context);
+            }
+            // Remote parent (from traceparent header)
+            if (parentContext.isRemote) {
+                return parentContext.sampled
+                    ? remoteParentSampled.shouldSample(context)
+                    : remoteParentNotSampled.shouldSample(context);
+            }
+            // Local parent (same process)
+            return parentContext.sampled
+                ? localParentSampled.shouldSample(context)
+                : localParentNotSampled.shouldSample(context);
+        },
+        description: `ParentBasedSampler{root=${root.description}}`,
+    };
+}
+//# sourceMappingURL=sampler.js.map

package/dist/sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.js","sourceRoot":"","sources":["../src/sampler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH;;GAEG;AACH,MAAM,UAAU,eAAe;IAC9B,OAAO;QACN,YAAY,EAAE,GAAG,EAAE,CAAC,mBAAmB;QACvC,WAAW,EAAE,iBAAiB;KAC9B,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC/B,OAAO;QACN,YAAY,EAAE,GAAG,EAAE,CAAC,MAAM;QAC1B,WAAW,EAAE,kBAAkB;KAC/B,CAAA;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAChD,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;IAEvD,IAAI,eAAe,KAAK,CAAC;QAAE,OAAO,gBAAgB,EAAE,CAAA;IACpD,IAAI,eAAe,KAAK,CAAC;QAAE,OAAO,eAAe,EAAE,CAAA;IAEnD,OAAO;QACN,YAAY,EAAE,GAAG,EAAE,CAClB,IAAI,CAAC,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,MAAM;QAC/D,WAAW,EAAE,uBAAuB,eAAe,GAAG;KACtD,CAAA;AACF,CAAC;AAeD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CACjC,OAAkC;IAElC,MAAM,EACL,IAAI,EACJ,mBAAmB,GAAG,eAAe,EAAE,EACvC,sBAAsB,GAAG,gBAAgB,EAAE,EAC3C,kBAAkB,GAAG,eAAe,EAAE,EACtC,qBAAqB,GAAG,gBAAgB,EAAE,GAC1C,GAAG,OAAO,CAAA;IAEX,OAAO;QACN,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE;YACzB,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAA;YAEjC,0CAA0C;YAC1C,IAAI,CAAC,aAAa,EAAE,CAAC;gBACpB,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;YAClC,CAAC;YAED,0CAA0C;YAC1C,IAAI,aAAa,CAAC,QAAQ,EAAE,CAAC;gBAC5B,OAAO,aAAa,CAAC,OAAO;oBAC3B,CAAC,CAAC,mBAAmB,CAAC,YAAY,CAAC,OAAO,CAAC;oBAC3C,CAAC,CAAC,sBAAsB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;YAChD,CAAC;YAED,8BAA8B;YAC9B,OAAO,aAAa,CAAC,OAAO;gBAC3B,CAAC,CAAC,kBAAkB,CAAC,YAAY,CAAC,OAAO,CAAC;gBAC1C,CAAC,CAAC,qBAAqB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;QAC/C,CAAC;QACD,WAAW,EAAE,2BAA2B,IAAI,CAAC,WAAW,GAAG;KAC3D,CAAA;AACF,CAAC"}

package/dist/trace-context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * W3C Trace Context utilities for distributed tracing.
+ * Implements the W3C Trace Context specification:
+ * https://www.w3.org/TR/trace-context/
+ *
+ * traceparent format: version-traceId-spanId-flags
+ * Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+ */
+export type TraceparentData = {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+};
+/**
+ * Generate a random 32-character hex trace ID (16 bytes).
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a random 16-character hex span ID (8 bytes).
+ */
+export declare function generateSpanId(): string;
+/**
+ * Parse a W3C traceparent header into its components.
+ * Returns null if the header is invalid.
+ */
+export declare function parseTraceparent(header: string): TraceparentData | null;
+/**
+ * Create a W3C traceparent header value.
+ */
+export declare function createTraceparent(traceId: string, spanId: string, sampled: boolean): string;
+//# sourceMappingURL=trace-context.d.ts.map

package/dist/trace-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.d.ts","sourceRoot":"","sources":["../src/trace-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAMvC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAkBvE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACd,MAAM,CAGR"}

package/dist/trace-context.js

@@ -0,0 +1,60 @@
+/**
+ * W3C Trace Context utilities for distributed tracing.
+ * Implements the W3C Trace Context specification:
+ * https://www.w3.org/TR/trace-context/
+ *
+ * traceparent format: version-traceId-spanId-flags
+ * Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+ */
+const TRACEPARENT_REGEX = /^00-([a-f0-9]{32})-([a-f0-9]{16})-([a-f0-9]{2})$/;
+/**
+ * Generate a random 32-character hex trace ID (16 bytes).
+ */
+export function generateTraceId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Generate a random 16-character hex span ID (8 bytes).
+ */
+export function generateSpanId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Parse a W3C traceparent header into its components.
+ * Returns null if the header is invalid.
+ */
+export function parseTraceparent(header) {
+    const match = header.match(TRACEPARENT_REGEX);
+    if (!match)
+        return null;
+    const [, traceId, spanId, flags] = match;
+    if (!traceId || !spanId || !flags)
+        return null;
+    // Validate trace ID is not all zeros
+    if (traceId === "00000000000000000000000000000000")
+        return null;
+    // Validate span ID is not all zeros
+    if (spanId === "0000000000000000")
+        return null;
+    return {
+        traceId,
+        spanId,
+        sampled: (Number.parseInt(flags, 16) & 0x01) === 1,
+    };
+}
+/**
+ * Create a W3C traceparent header value.
+ */
+export function createTraceparent(traceId, spanId, sampled) {
+    const flags = sampled ? "01" : "00";
+    return `00-${traceId}-${spanId}-${flags}`;
+}
+//# sourceMappingURL=trace-context.js.map

package/dist/trace-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.js","sourceRoot":"","sources":["../src/trace-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,iBAAiB,GAAG,kDAAkD,CAAA;AAQ5E;;GAEG;AACH,MAAM,UAAU,eAAe;IAC9B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;IAChC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;IAC7B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SACtB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAA;AACX,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC7B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;IAC/B,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;IAC7B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SACtB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAA;AACX,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAA;IAC7C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IAEvB,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,CAAA;IACxC,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IAE9C,qCAAqC;IACrC,IAAI,OAAO,KAAK,kCAAkC;QAAE,OAAO,IAAI,CAAA;IAE/D,oCAAoC;IACpC,IAAI,MAAM,KAAK,kBAAkB;QAAE,OAAO,IAAI,CAAA;IAE9C,OAAO;QACN,OAAO;QACP,MAAM;QACN,OAAO,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;KAClD,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAChC,OAAe,EACf,MAAc,EACd,OAAgB;IAEhB,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;IACnC,OAAO,MAAM,OAAO,IAAI,MAAM,IAAI,KAAK,EAAE,CAAA;AAC1C,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,256 @@
+import type { Instrumentation } from "./instrument/types.js";
+import type { Sampler } from "./sampler.js";
+export type VidentConfig = {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+    serviceName?: string;
+    instrumentations?: Instrumentation[];
+    /**
+     * Sampler for tracing. Default: parentBasedSampler with 100% root sampling.
+     * @example
+     * // 10% sampling for new traces, respect parent decisions
+     * sampler: parentBasedSampler({ root: traceIdRatioSampler(0.1) })
+     */
+    sampler?: Sampler;
+    /**
+     * Explicitly enable/disable the SDK. When false, all methods are no-ops.
+     * Useful for test environments: `enabled: process.env.NODE_ENV !== 'test'`
+     * Default: true if apiKey is provided, false otherwise.
+     */
+    enabled?: boolean;
+};
+export type { Instrumentation };
+export type Project = {
+    id: string;
+    name: string;
+    slug: string;
+    orgId: string;
+    timezone: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type CreateProjectInput = {
+    name: string;
+    slug: string;
+    orgId: string;
+    timezone?: string;
+};
+export type UpdateProjectInput = {
+    name?: string;
+    timezone?: string;
+};
+export type CheckStatus = "NEW" | "UP" | "LATE" | "DOWN" | "PAUSED";
+export type ScheduleType = "PERIOD" | "CRON";
+export type Check = {
+    id: string;
+    projectId: string;
+    name: string;
+    slug: string | null;
+    scheduleType: ScheduleType;
+    scheduleValue: string;
+    graceSeconds: number;
+    timezone: string | null;
+    status: CheckStatus;
+    lastPingAt: string | null;
+    nextExpectedAt: string | null;
+    alertOnRecovery: boolean;
+    reminderIntervalHours: number | null;
+    channelIds: string[];
+    createdAt: string;
+    updatedAt: string;
+};
+export type CreateCheckInput = {
+    name: string;
+    slug?: string;
+    scheduleType: ScheduleType;
+    scheduleValue: string;
+    graceSeconds?: number;
+    timezone?: string;
+    alertOnRecovery?: boolean;
+    reminderIntervalHours?: number;
+};
+export type UpdateCheckInput = Partial<CreateCheckInput> & {
+    channelIds?: string[];
+};
+export type ChannelType = "EMAIL" | "SLACK_WEBHOOK" | "SLACK_APP" | "DISCORD" | "PAGERDUTY" | "OPSGENIE" | "WEBHOOK";
+export type EmailChannelConfig = {
+    email: string;
+};
+export type SlackWebhookChannelConfig = {
+    webhookUrl: string;
+};
+export type SlackAppChannelConfig = {
+    accessToken: string;
+    channelId: string;
+    webhookUrl?: string;
+};
+export type DiscordChannelConfig = {
+    webhookUrl: string;
+};
+export type PagerDutyChannelConfig = {
+    routingKey: string;
+};
+export type OpsgenieChannelConfig = {
+    apiKey: string;
+    region?: "us" | "eu";
+};
+export type WebhookChannelConfig = {
+    url: string;
+    secret?: string;
+};
+export type ChannelConfig = EmailChannelConfig | SlackWebhookChannelConfig | SlackAppChannelConfig | DiscordChannelConfig | PagerDutyChannelConfig | OpsgenieChannelConfig | WebhookChannelConfig;
+export type Channel = {
+    id: string;
+    projectId: string;
+    type: ChannelType;
+    name: string;
+    config: ChannelConfig;
+    createdAt: string;
+    updatedAt: string;
+};
+export type CreateChannelInput = {
+    type: "EMAIL";
+    name: string;
+    config: EmailChannelConfig;
+} | {
+    type: "SLACK_WEBHOOK";
+    name: string;
+    config: SlackWebhookChannelConfig;
+} | {
+    type: "SLACK_APP";
+    name: string;
+    config: SlackAppChannelConfig;
+} | {
+    type: "DISCORD";
+    name: string;
+    config: DiscordChannelConfig;
+} | {
+    type: "PAGERDUTY";
+    name: string;
+    config: PagerDutyChannelConfig;
+} | {
+    type: "OPSGENIE";
+    name: string;
+    config: OpsgenieChannelConfig;
+} | {
+    type: "WEBHOOK";
+    name: string;
+    config: WebhookChannelConfig;
+};
+export type UpdateChannelInput = {
+    name?: string;
+    config?: ChannelConfig;
+};
+export type Organization = {
+    id: string;
+    name: string;
+    slug: string;
+    plan: string;
+    trialEndsAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type CreateOrganizationInput = {
+    name: string;
+    slug: string;
+};
+export type UpdateOrganizationInput = {
+    name?: string;
+};
+export type ApiKey = {
+    id: string;
+    projectId: string;
+    name: string;
+    prefix: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+};
+export type ApiKeyCreated = ApiKey & {
+    key: string;
+};
+export type CreateApiKeyInput = {
+    name: string;
+};
+export type UptimeDay = {
+    date: string;
+    upPercent: number;
+    upMinutes: number;
+    downMinutes: number;
+    totalPings: number;
+};
+export type CheckStats = {
+    checkId: string;
+    days: UptimeDay[];
+};
+export type PingOptions = {
+    type?: "success" | "start" | "fail";
+    body?: string;
+};
+export type WrapOptions = {
+    /** Send START ping before execution to track duration. Default: false */
+    trackDuration?: boolean;
+};
+export type SpanKind = "server" | "client" | "internal" | "producer" | "consumer";
+export type SpanOptions = {
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean>;
+    /** Parent span context for distributed tracing */
+    parent?: SpanContext;
+    /** Mark this span as an intentional root span (no parent expected) */
+    root?: boolean;
+};
+export type TraceOptions = {
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean>;
+    /** Parent span context for distributed tracing */
+    parent?: SpanContext;
+    /** Mark this trace as an intentional root (no parent expected) */
+    root?: boolean;
+};
+export type SpanContext = {
+    traceId: string;
+    spanId: string;
+    /** Whether this context came from a remote service */
+    isRemote?: boolean;
+    /** Whether this span was sampled */
+    sampled?: boolean;
+};
+export type SpanInterface = {
+    spanId: string;
+    traceId: string;
+    name: string;
+    end: (options?: {
+        error?: Error;
+    }) => void;
+    setAttributes: (attrs: Record<string, string | number | boolean>) => void;
+    updateName: (name: string) => void;
+    context: () => SpanContext;
+};
+export type PaginationParams = {
+    page?: number;
+    limit?: number;
+};
+export type PaginatedResponse<T> = {
+    data: T[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+};
+/**
+ * Creates an async generator that iterates through all pages of a paginated endpoint.
+ * @example
+ * for await (const project of paginate(params => client.projects.list(params))) {
+ *   console.log(project.name)
+ * }
+ */
+export declare function paginate<T>(fetcher: (params: PaginationParams) => Promise<PaginatedResponse<T>>, params?: Omit<PaginationParams, "page">): AsyncGenerator<T, void, unknown>;
+/**
+ * Fetches all items from a paginated endpoint into an array.
+ * @example
+ * const allProjects = await fetchAll(params => client.projects.list(params))
+ */
+export declare function fetchAll<T>(fetcher: (params: PaginationParams) => Promise<PaginatedResponse<T>>, params?: Omit<PaginationParams, "page">): Promise<T[]>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,33 @@
+/**
+ * Creates an async generator that iterates through all pages of a paginated endpoint.
+ * @example
+ * for await (const project of paginate(params => client.projects.list(params))) {
+ *   console.log(project.name)
+ * }
+ */
+export async function* paginate(fetcher, params) {
+    let page = 1;
+    const limit = params?.limit ?? 20;
+    while (true) {
+        const response = await fetcher({ page, limit });
+        for (const item of response.data) {
+            yield item;
+        }
+        if (page >= response.totalPages)
+            break;
+        page++;
+    }
+}
+/**
+ * Fetches all items from a paginated endpoint into an array.
+ * @example
+ * const allProjects = await fetchAll(params => client.projects.list(params))
+ */
+export async function fetchAll(fetcher, params) {
+    const items = [];
+    for await (const item of paginate(fetcher, params)) {
+        items.push(item);
+    }
+    return items;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAiSA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAC9B,OAAoE,EACpE,MAAuC;IAEvC,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,EAAE,CAAA;IAEjC,OAAO,IAAI,EAAE,CAAC;QACb,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QAC/C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAClC,MAAM,IAAI,CAAA;QACX,CAAC;QACD,IAAI,IAAI,IAAI,QAAQ,CAAC,UAAU;YAAE,MAAK;QACtC,IAAI,EAAE,CAAA;IACP,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC7B,OAAoE,EACpE,MAAuC;IAEvC,MAAM,KAAK,GAAQ,EAAE,CAAA;IACrB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC;QACpD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjB,CAAC;IACD,OAAO,KAAK,CAAA;AACb,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "vident-sdk",
+	"version": "0.11.0",
+	"description": "TypeScript SDK for Vident - monitoring, tracing, and error tracking",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
+		"./instrument": {
+			"import": "./dist/instrument/index.js",
+			"types": "./dist/instrument/index.d.ts"
+		}
+	},
+	"files": ["dist"],
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"clean": "rm -rf dist",
+		"generate-types": "openapi-typescript http://localhost:3000/openapi.json -o src/types.generated.ts"
+	},
+	"keywords": ["vident", "monitoring", "tracing", "observability", "apm"],
+	"license": "MIT",
+	"peerDependencies": {
+		"@aws-sdk/smithy-client": ">=3.0.0",
+		"@prisma/client": ">=5.0.0",
+		"hono": ">=4.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@aws-sdk/smithy-client": {
+			"optional": true
+		},
+		"@prisma/client": {
+			"optional": true
+		},
+		"hono": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"hono": "^4.0.0",
+		"openapi-typescript": "^7.4.4",
+		"typescript": "^5.7.2"
+	}
+}