neatlogs 1.1.0 → 1.1.2

package/dist/index.d.ts

@@ -40,26 +40,16 @@ interface InitOptions {
     baseUrl?: string;
     /** Name of the workflow being traced. Defaults to process.argv[1]. */
     workflowName?: string;
-    /** Explicit session ID for grouping traces. */
-    sessionId?: string;
-    /** Auto-generate a session ID if none provided. Defaults to false. */
-    autoSession?: boolean;
     /**
      * Operator identifier — whoever is RUNNING the SDK (a developer, a service
      * account, a CI job). Attached to all spans as a resource attribute. This is
      * NOT the end-user of your application.
+     *
+     * Session and end-user identity are PER-REQUEST, not process-global, so they
+     * are never set here. Declare them at the trace root via `trace()`/`span()`
+     * options, or for pure-`wrap()` code via the request-scoped `identify()`.
      */
     userId?: string;
-    /**
-     * Process-global default for the END-USER — the user of your application.
-     * Use this for single-user processes (CLI, per-user worker) and pure-`wrap()`
-     * setups, where it lands on the root span automatically. On a multi-tenant
-     * server set the end-user per request via `trace({ endUserId })` instead.
-     * One end-user per trace; the backend rolls it up to the trace and its session.
-     */
-    endUserId?: string;
-    /** Optional arbitrary end-user fields stored as JSON (e.g. { plan: 'pro' }). */
-    endUserMetadata?: Record<string, any>;
     /** Tags to attach to all spans. Must be string array. */
     tags?: string[];
     /** Custom metadata to attach to all spans. */
@@ -82,7 +72,7 @@ interface InitOptions {
     pii?: 'redact' | 'hash' | false;
     /** SDK version override. */
     version?: string;
-    /** Backend endpoint URL. Defaults to https://staging-cloud.neatlogs.com */
+    /** Base ingest endpoint. Defaults to https://ingest.neatlogs.com. */
     endpoint?: string;
     /** Maximum spans per export batch. Defaults to 100. */
     batchSize?: number;
@@ -121,6 +111,12 @@ interface SpanOptions {
     parameters?: Record<string, any>;
     /** JSON schema describing the tool interface (for kind: MCP_TOOL). */
     toolJsonSchema?: Record<string, any>;
+    /**
+     * Session this trace belongs to — groups the traces of a multi-turn
+     * conversation (one turn = one trace). Usually set on the WORKFLOW root. The
+     * backend groups traces by it; when absent it falls back to the trace id.
+     */
+    sessionId?: string;
     /**
      * Identifier of the END-USER this trace belongs to — the user of your
      * application, not the operator running the SDK. The backend rolls it up to
@@ -216,8 +212,9 @@ declare function getSessionConfig(): Record<string, any>;
  * and executes the provided callback within the span.
  *
  * **Session-Aware Trace Creation:**
- * - If `session_id` is set in init() AND no active parent span exists,
- *   this creates a NEW root trace (for multi-turn conversations).
+ * - If a session id is resolved (per-call `sessionId` or the request-scoped
+ *   `identify()` context) AND no active parent span exists, this creates a NEW
+ *   root trace (for multi-turn conversations).
  * - Otherwise, creates a normal child span within the existing trace.
  *
  * @param options - Trace configuration options
@@ -323,6 +320,28 @@ declare function Span(options: SpanOptions): <T extends (...args: any[]) => any>
  */
 declare function log(msgTemplate: string, options?: Record<string, any>): void;
 
+interface IdentifyOptions {
+    sessionId?: string;
+    endUserId?: string;
+    endUserMetadata?: Record<string, any>;
+}
+/**
+ * Bind session / end-user identity for the duration of `fn`.
+ *
+ * Only defined fields are set, so a nested `identify()` overrides one field
+ * without clearing the others (it merges onto the enclosing store). The previous
+ * store is automatically restored when `fn` returns / rejects. Returns whatever
+ * `fn` returns (sync value or Promise).
+ *
+ * @example
+ * ```typescript
+ * await neatlogs.identify({ sessionId: 'chat_123' }, async () => {
+ *   await wrappedClient.chat.completions.create(...);
+ * });
+ * ```
+ */
+declare function identify<T>(opts: IdentifyOptions, fn: () => T): T;
+
 interface ContextSetter {
     set(template: string, variables: Record<string, any>): void;
 }
@@ -571,6 +590,6 @@ declare function registerCrewaiTask(task: {
  * SDK version. Kept in sync with package.json by the `version:sync` script
  * (runs automatically on `prebuild`). Do not edit by hand — bump package.json.
  */
-declare const __version__ = "1.1.0";
+declare const __version__ = "1.1.2";
 
-export { type CachedPrompt, type InitOptions, type MaskFunction, PromptApiError, PromptClient, PromptClientError, PromptHandle, type PromptMessage, PromptNotFoundError, PromptTemplate, Span, type SpanKind, type SpanOptions, type TraceOptions, UserPromptTemplate, __version__, bindTemplates, createPrompt, deletePrompt, fetchPrompt, flush, getMastraObservability, getPrompt, getSessionConfig, init, isDebugEnabled, listPrompts, log, registerCrewaiTask, removeTag, saveAsVersion, shutdown, span, trace, updatePrompt };
+export { type CachedPrompt, type InitOptions, type MaskFunction, PromptApiError, PromptClient, PromptClientError, PromptHandle, type PromptMessage, PromptNotFoundError, PromptTemplate, Span, type SpanKind, type SpanOptions, type TraceOptions, UserPromptTemplate, __version__, bindTemplates, createPrompt, deletePrompt, fetchPrompt, flush, getMastraObservability, getPrompt, getSessionConfig, identify, init, isDebugEnabled, listPrompts, log, registerCrewaiTask, removeTag, saveAsVersion, shutdown, span, trace, updatePrompt };