@raindrop-ai/openai-managed-agents 0.0.4 → 0.0.5

package/README.md

@@ -120,6 +120,18 @@ responsibility.
 `users.identify`, and `signals.track` expose the shared core enrichment API.
 `flush()` ships current buffers; `shutdown()` also closes unfinished captures.
 
+## Shared client options
+
+`createRaindropOpenAIManagedAgents(...)` also takes the options every Raindrop JS integration shares:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `redactPii` | `boolean` | `false` | Redact PII (emails, phone numbers, card numbers, addresses, secrets) from event input/output before it leaves the process |
+| `redactPiiFields` | `PiiFieldMap` | - | More wire field paths to redact when `redactPii` is on, e.g. `{ event: ["properties.customer.email"] }`; add `properties["error.message"]` to also redact error messages |
+| `flushTimeoutMs` | `number` | `10000` | Deadline for `flush()` / `shutdown()`. Both resolve to a result (`delivered`, `dropped`, `queued`, ...) and never reject |
+
+`flush()` and `shutdown()` resolve to `{ delivered, timedOut, dropped, queued, inFlight }` and never reject; ignoring the result is fine.
+
 ## Tool catalog capture (`ai.prompt.tools`)
 
 **Agent configuration, not exact per-call capture.** Model calls run inside
@@ -141,6 +153,20 @@ is enabled.
 | --- | --- |
 | `tools` (on `createRaindropOpenAIManagedAgents({ tools })` or `wrap(client, { tools })`) | Overrides the tool catalog recorded as `ai.prompt.tools` on every model span. Use when the integration cannot see the tools the model was given. Replaces the agent definition entirely (`tools: []` records an empty catalog) and carries no `source` attribute. |
 
+## Your properties win
+
+Properties you pass (as defaults, per call, or through `events.setProperties` / `events.patch` / `events.finish`) are merged into the event. If one of your keys has the same name as a key the integration sets itself, such as `ai.usage.*`, `ai.provider`, `error.type` / `error.message`, or the integration's own prefixed keys, your value is kept, whatever order the updates are sent in. With `debug` on, the integration logs each key you override.
+
+## Event ids
+
+Set each turn's id with the `eventId: (turnId) => string` option; the event and every span of the turn carry it. After a turn finishes, `raindrop.lastEventId` holds its id, for attaching a signal or feedback:
+
+```ts
+await raindrop.signals.track({ eventId: raindrop.lastEventId!, name: "thumbs_up", type: "feedback", sentiment: "POSITIVE" });
+```
+
+Finishes you make through `raindrop.events.*` don't change `lastEventId`. It holds the last turn finished anywhere in the process, so on a client shared by concurrent turns, use the id you passed instead.
+
 ## Limits
 
 The service does not expose individual inference requests. Captures represent

package/dist/index.d.mts

@@ -98,6 +98,49 @@ type AppGitContext = Pick<AppGitContextImpl, "snapshot" | "snapshotForReplay" |
     releaseOperation?: (eventId: string, owner: AppGitOperationOwner) => void;
 };
 declare const AppGitContext: typeof AppGitContextImpl;
+
+type FeatureFlagValue = string | number | boolean;
+type FeatureFlags = string[] | Record<string, FeatureFlagValue>;
+
+/**
+ * What `flush()` / `shutdown()` resolve to (CONTRACT 1.2.1). Safe to ignore:
+ * they never reject, and ignoring the result changes nothing.
+ *
+ * `delivered` is true when everything enqueued before the call was handed to
+ * ingest. A payload ingest rejected permanently (a non-429, non-408 4xx)
+ * counts as delivered: ingest saw it and refused it.
+ */
+type FlushResult = {
+    delivered: boolean;
+    /** The call returned at its deadline with work outstanding. */
+    timedOut: boolean;
+    /** Payloads given up on: cut off mid-flight at the deadline, retries ran out, or left at shutdown. */
+    dropped: number;
+    /** Payloads still queued for a later send (never sent, or waiting on a retry or Retry-After pause). */
+    queued: number;
+    /**
+     * Sends started before the call and still running at its deadline. They are
+     * cut off then: a request in flight is dropped (not resent), and one waiting
+     * to retry goes back to its queue.
+     */
+    inFlight: number;
+};
+/**
+ * `FlushResult` as the declared return of public `flush()`/`shutdown()`
+ * methods. The `void &` keeps `Promise<FlushResultCompat>` assignable to
+ * `Promise<void>`, so code that typed these methods as returning
+ * `Promise<void>` (interfaces, callbacks) keeps compiling, while callers can
+ * still read the result's fields.
+ */
+type FlushResultCompat = void & FlushResult;
+
+/** Payload kinds a field map can name: event items on `events/track` and
+ *  `events/track_partial`, `signals/track` items and `users/identify` items. */
+type PiiPayloadKind = "event" | "signal" | "identify";
+/** Extra fields to redact, per payload kind (CONTRACT 11.2). */
+type PiiFieldMap = {
+    [K in PiiPayloadKind]?: readonly string[];
+};
 type Attachment = {
     type: string;
     role: string;
@@ -122,6 +165,14 @@ type Patch = {
     usage?: EventUsage;
     error?: unknown;
     properties?: Record<string, unknown>;
+    /**
+     * Properties the integrator supplied (setup defaults, per-call context, the
+     * manual events API), as opposed to keys an integration derives itself. On a
+     * key clash these win over `properties` and over the keys derived from
+     * `usage` / `error`, whatever order the updates are sent in (wrapper profile
+     * W6). Sent inside the event's `properties`; this is not a wire field.
+     */
+    callerProperties?: Record<string, unknown>;
     featureFlags?: Record<string, string>;
     attachments?: Attachment[];
     isPending?: boolean;
@@ -138,6 +189,9 @@ type SignalInput = {
     comment?: string;
     after?: string;
 };
+type ResumeOptions = Pick<Patch, "userId" | "convoId" | "eventName">;
+/** Fields `finish` accepts. */
+type FinishFields = Pick<Patch, "output" | "model" | "usage" | "error" | "properties" | "callerProperties" | "featureFlags" | "userId">;
 type EventShipperOptions = {
     appGit?: AppGitOptions | false;
     /** Share with the trace shipper so one operation uses one source snapshot. */
@@ -171,6 +225,27 @@ type EventShipperOptions = {
      * Defaults to 1,000,000 (matching the Python SDK).
      */
     maxTextFieldChars?: number;
+    /**
+     * Redact PII (emails, phone numbers, card numbers, addresses, secrets) from
+     * event input and output before they leave the process. Off by default.
+     */
+    redactPii?: boolean;
+    /**
+     * More fields to redact when `redactPii` is on, per payload kind, as wire
+     * field paths (`{ event: ["properties.customer.email"], signal: ["comment"],
+     * identify: ["traits.email"] }`). Adds to the default `ai_data.input` and
+     * `ai_data.output`; never removes them (CONTRACT 11.2, see `pii-fields.ts`).
+     */
+    redactPiiFields?: PiiFieldMap;
+    /**
+     * Deadline in ms for `flush()` and `shutdown()`, retries and Retry-After
+     * waits included (default 10,000; CONTRACT 1.2.1). At the deadline a flush
+     * returns: payloads not yet sent stay queued for later, a request cut off
+     * mid-flight is not resent, and `shutdown()` drops what is left.
+     */
+    flushTimeoutMs?: number;
+    /** Tags every event with `raindrop.wizardSession` (set by the setup wizard). */
+    wizardSession?: string;
 };
 declare class EventShipper {
     private appGitContext;
@@ -190,7 +265,26 @@ declare class EventShipper {
     private sticky;
     private timers;
     private inFlight;
+    /** Updates queued with `enqueue` whose send has not settled yet. */
+    private background;
+    /** Background updates dropped since the last flush()/shutdown() result. */
+    private backgroundDrops;
+    /** Cuts off sends still running at a flush or shutdown deadline. */
+    private readonly cutOff;
     private maxTextFieldCharsOpt;
+    private redactPii;
+    private piiFields;
+    private wizardSession;
+    /**
+     * Events finished in this process, oldest first, capped at
+     * FINISHED_EVENT_MEMORY, so a repeated finish can be warned about.
+     */
+    private finishedEventIds;
+    /** The latest send per event; the next send for that event waits for it. */
+    private sendChains;
+    private flushTimeoutMs;
+    /** Signal/identify sends a flush deadline deferred; retried later. */
+    private deferredSends;
     /**
      * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
      * Checked before every POST issued during the final flush.
@@ -211,29 +305,120 @@ declare class EventShipper {
     private authHeaders;
     private requestHeaders;
     /**
-     * Build the retry/timeout options for one POST, honoring the shutdown
-     * deadline. Returns `null` when the shutdown drain window is exhausted —
-     * the caller must drop the payload (with a rate-limited warning) instead
-     * of issuing a request that could outlive process exit.
-     *
-     * Checked fresh on EVERY send, so a shutdown that begins while the flush
-     * path is mid-drain takes effect immediately: no further retries, and the
-     * per-attempt timeout is clamped to the remaining window. After
-     * `shutdown()` returns (deadline cleared, `hasShutdown` still set),
-     * sends — late callers, or flush work the deadline abandoned mid-drain —
-     * run as a single short attempt rather than regaining the full retry
-     * schedule.
+     * Retry/timeout options for one POST. While `shutdown()` drains, sends retry
+     * within its window (deadline = the shutdown deadline); a flush passes its
+     * own deadline. `null` when the shutdown window is spent: the caller drops
+     * the payload with a warning. After `shutdown()` returns, late sends get a
+     * single short attempt rather than the full retry schedule.
      */
     private requestOpts;
+    private shuttingDown;
     patch(eventId: string, patch: Patch): Promise<void>;
-    finish(eventId: string, patch: Pick<Patch, "output" | "model" | "usage" | "error" | "properties" | "featureFlags" | "userId">): Promise<void>;
-    flush(): Promise<void>;
-    shutdown(): Promise<void>;
+    /**
+     * Queue an update without waiting for any network send: for integrations,
+     * whose captured call must return as soon as the update is queued (rule C9,
+     * hot path). A finishing update starts its send in the background; `flush()`
+     * and `shutdown()` wait for it within their deadline and count it in their
+     * result. Never throws or rejects.
+     */
+    enqueue(eventId: string, patch: Patch): void;
+    /** `finish()` without waiting for the send; see `enqueue`. */
+    enqueueFinish(eventId: string, patch?: FinishFields): void;
+    /**
+     * Caller properties win over everything the integration derived (W6). A
+     * clash is intended by the caller, so it is only logged in debug mode.
+     */
+    private withCallerProperties;
+    private warnBackgroundFailure;
+    /**
+     * Id of the last event an integration finished in this process (manual
+     * events API finishes excluded): what integrations expose as `lastEventId`
+     * (wrapper profile W10).
+     */
+    get lastFinishedEventId(): string | undefined;
+    private lastFinished;
+    private patchWithFate;
+    /**
+     * A second finish for an event is still sent (ingest finalizes once and
+     * treats it as an update, CONTRACT §10.2), but it usually means several
+     * calls share one event id by mistake, so it is warned about.
+     */
+    private noteFinish;
+    /**
+     * An event finished with no input, output or attachments is almost always a
+     * caller bug (CONTRACT §14.2, rule C5); it is sent anyway and warned about.
+     * Not for a resumed event: its content may have been sent by another process.
+     */
+    private noteEmptyFinish;
+    /**
+     * Continue an event that was begun elsewhere (another process, a queue
+     * worker, a later request) using only its id. No request is sent; later
+     * `patch` / `finish` calls for this id are sent even without a `userId`,
+     * and ingest keeps the user, conversation and start time it already has.
+     * Pass `userId` / `convoId` / `eventName` if you have them.
+     */
+    resume(eventId: string, options?: ResumeOptions): void;
+    finish(eventId: string, patch: FinishFields): Promise<void>;
+    /**
+     * Send everything buffered, open (pending) events included, within
+     * `flushTimeoutMs` (CONTRACT 1.2.1). Resolves, never rejects, to whether it
+     * all reached ingest; when it didn't, it also warns. At the deadline,
+     * payloads not yet sent stay queued for a later send and a request cut off
+     * mid-flight is dropped. Sends already running when it was called are
+     * waited for up to the deadline and then cut off.
+     */
+    flush(): Promise<FlushResultCompat>;
+    private drainAll;
+    /**
+     * Flush within `flushTimeoutMs` and stop. Sends retry while the window
+     * allows; whatever is left at the deadline is dropped with a warning, so a
+     * dead network can never wedge process exit. Resolves, never rejects.
+     */
+    shutdown(): Promise<FlushResultCompat>;
     trackSignal(signal: SignalInput): Promise<void>;
     identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    /**
+     * Send a signal or identify body. Tracked so `flush()` waits for it. A send
+     * a flush deadline deferred is kept and retried later (outside shutdown).
+     */
+    private sendDirect;
+    private deferSend;
+    private warnSendDropped;
+    /** The payload with its PII fields redacted when `redactPii` is on (CONTRACT 11.2). */
+    private redactFields;
     private warnShutdownDrop;
     private flushOne;
+    /**
+     * Put an unsent update back under any newer one and send it later
+     * (CONTRACT 1.2.1). During shutdown it is dropped instead.
+     */
+    private requeue;
+    private sendAccumulated;
 }
+
+/** Fields `events.finish` accepts (the same set as `EventShipper.finish`). */
+type FinishPatch = Parameters<EventShipper["finish"]>[1];
+/**
+ * The manual event API every integration exposes as `client.events`. One
+ * implementation, so every package offers the same calls with the same
+ * behaviour (dawn docs/sdk-contract/sdk-plan.md, rules C2 and C11).
+ */
+type EventsApi = {
+    /** Update an event: any subset of its fields. */
+    patch(eventId: string, patch: Patch): Promise<void>;
+    /** Finalize an event, optionally with its output and other final fields. */
+    finish(eventId: string, patch?: FinishPatch): Promise<void>;
+    addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
+    setProperties(eventId: string, properties: Record<string, unknown>): Promise<void>;
+    setFeatureFlags(eventId: string, featureFlags: FeatureFlags): Promise<void>;
+    /**
+     * Continue an event begun elsewhere (another process, a queue worker, a
+     * later request) using only its id. Later calls for this id are sent even
+     * without a `userId`; ingest keeps the user, conversation and start time it
+     * already has.
+     */
+    resume(eventId: string, options?: ResumeOptions): void;
+};
 /**
  * Hook fired per OTLP span right before the span is shipped (to the Raindrop
  * API and to a local debugger). Lets callers inspect, rewrite, or drop the
@@ -270,6 +455,12 @@ type TraceShipperOptions = {
     flushIntervalMs?: number;
     maxBatchSize?: number;
     maxQueueSize?: number;
+    /**
+     * Deadline in ms for `flush()` and `shutdown()` (default 10,000; CONTRACT
+     * 1.2.1). Spans not yet sent at a flush deadline stay queued; a request cut
+     * off mid-flight is not resent; `shutdown()` drops what is left.
+     */
+    flushTimeoutMs?: number;
     sdkName?: string;
     serviceName?: string;
     serviceVersion?: string;
@@ -349,10 +540,13 @@ declare class TraceShipper {
     private flushIntervalMs;
     private maxBatchSize;
     private maxQueueSize;
+    private flushTimeoutMs;
     private projectId;
     private queue;
     private timer;
     private inFlight;
+    /** Cuts off sends still running at a flush or shutdown deadline. */
+    private readonly cutOff;
     /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
     private transformSpanHook;
@@ -438,12 +632,66 @@ declare class TraceShipper {
         status?: OtlpSpanStatus;
     }): void;
     enqueue(span: OtlpSpan): void;
-    flush(): Promise<void>;
-    /** See EventShipper.requestOpts — same shutdown-budget semantics. */
+    private scheduleDrain;
+    /**
+     * Send every queued span within `flushTimeoutMs` (CONTRACT 1.2.1). Resolves,
+     * never rejects, to whether they all reached ingest, and warns when they
+     * didn't. Spans not yet sent at the deadline stay queued.
+     */
+    flush(): Promise<FlushResultCompat>;
+    private drainWithin;
+    /** Send queued batches; with a deadline, a deferred batch goes back on the queue. */
+    private drain;
+    /** See EventShipper.requestOpts — same deadline semantics. */
     private requestOpts;
-    shutdown(): Promise<void>;
+    private scheduleFor;
+    /**
+     * Flush within `flushTimeoutMs` and stop; spans left at the deadline are
+     * dropped with a warning. Resolves, never rejects.
+     */
+    shutdown(): Promise<FlushResultCompat>;
 }
 
+/**
+ * The client options every integration accepts, with one meaning everywhere.
+ * Integration option types extend this; their own options stay beside it.
+ * (Each field also takes `undefined`, for `exactOptionalPropertyTypes` users.)
+ */
+type RaindropClientOptions = {
+    /** Raindrop write key. Without one (and no local Workshop) nothing is sent. */
+    writeKey?: string | undefined;
+    /** Ingest base URL. Defaults to `https://api.raindrop.ai/v1`. */
+    endpoint?: string | undefined;
+    /** Project slug, sent as `X-Raindrop-Project-Id`. Unset sends no header. */
+    projectId?: string | undefined;
+    /** Log telemetry activity to the console. */
+    debug?: boolean | undefined;
+    /** Application Git identity. Auto-detects the commit SHA by default; `false` turns it off. */
+    appGit?: AppGitOptions | false | undefined;
+    /**
+     * Per-field character cap for captured text. Longer values end with
+     * `...[truncated by raindrop]`. Defaults to 1,000,000.
+     */
+    maxTextFieldChars?: number | undefined;
+    /**
+     * Redact PII (emails, phone numbers, card numbers, addresses, secrets) from
+     * event input and output before it leaves the process. Off by default.
+     */
+    redactPii?: boolean | undefined;
+    /**
+     * More fields to redact when `redactPii` is on, per payload kind, as wire
+     * field paths (`{ event: ["properties.customer.email"] }`). Adds to the
+     * default `ai_data.input` and `ai_data.output`.
+     */
+    redactPiiFields?: PiiFieldMap | undefined;
+    /**
+     * Deadline in ms for `flush()` and `shutdown()`, retries included (default
+     * 10,000). At the deadline they return: unsent payloads stay queued (a
+     * shutdown drops them) and a request cut off mid-flight is not resent.
+     */
+    flushTimeoutMs?: number | undefined;
+};
+
 /**
  * Run telemetry egress with OpenTelemetry tracing suppressed.
  *
@@ -543,7 +791,7 @@ type SessionContext = {
      */
     tools?: PromptToolsOverride | undefined;
 };
-type OpenAIManagedAgentsOptions = SessionContext & {
+type OpenAIManagedAgentsOptions = SessionContext & RaindropClientOptions & {
     writeKey?: string | undefined;
     endpoint?: string | undefined;
     projectId?: string | undefined;
@@ -585,20 +833,21 @@ declare class RaindropManagedAgentsHandler {
 type RaindropOpenAIManagedAgentsClient = {
     handler: RaindropManagedAgentsHandler;
     wrap(client: OpenAI, context?: SessionContext): OpenAI;
-    events: {
-        patch(eventId: string, patch: Patch): Promise<void>;
-        finish(eventId: string, patch: Pick<Patch, "output" | "model" | "properties">): Promise<void>;
-        addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
-        setProperties(eventId: string, properties: NonNullable<Patch["properties"]>): Promise<void>;
-    };
+    /**
+     * Event id of the last turn this integration finished, or `undefined`
+     * before the first. Use it to attach a signal or feedback to that turn.
+     * Finishes made through `events.*` don't change it.
+     */
+    readonly lastEventId: string | undefined;
+    events: EventsApi;
     users: {
         identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
     };
     signals: {
         track(signal: SignalInput): Promise<void>;
     };
-    flush(): Promise<void>;
-    shutdown(): Promise<void>;
+    flush(): Promise<FlushResultCompat>;
+    shutdown(): Promise<FlushResultCompat>;
 };
 declare function createRaindropOpenAIManagedAgents(opts?: OpenAIManagedAgentsOptions): RaindropOpenAIManagedAgentsClient;