lumnisai 0.5.33 → 0.5.34

package/dist/index.cjs

@@ -3402,9 +3402,9 @@ class ResponsesResource {
       "expandFromResponse",
       "expand_from_response"
     );
-    if (typeof expandFromResponse !== "string" || !expandFromResponse.trim()) {
+    if (expandFromResponse !== void 0 && (typeof expandFromResponse !== "string" || !expandFromResponse.trim())) {
       throw new ValidationError(
-        "expandFromResponse is required for engagement_expansion and must be a non-empty string"
+        "expandFromResponse must be a non-empty string when provided for engagement_expansion"
       );
     }
     for (const [camel, snake] of [
@@ -3886,26 +3886,28 @@ class ResponsesResource {
     });
   }
   /**
-   * Find new people by walking outward from a saved content-intelligence package.
+   * Find new people by walking outward from a saved engagement package.
    *
-   * Hop 1 pulls the other engagers of the package's best posts. Additional hops
-   * select the highest-fit new people, rank posts from their feeds, and pull the
-   * engagers of those posts. Collection breadth is derived from `limit` unless
-   * `postsPerHop` is set explicitly. At the default limit, collection is about
-   * 300 credits for one hop and 1,060 for three hops; enrichment and validation
-   * use the standard deep-search economics on top.
+   * With `expandFromResponse`, hop 1 pulls the other engagers of that response's
+   * saved package. Without it, the backend first finds a seed audience from the
+   * prompt, collects and saves its package, then expands it. Additional hops
+   * select the highest-fit new people, rank posts from their feeds, and pull
+   * their engagers. Collection breadth is derived from `limit` unless
+   * `postsPerHop` is explicit. At the default limit, hop collection is about
+   * 300 credits for one hop and 1,060 for three; prompt-only seed collection,
+   * enrichment, and validation are additional.
    *
    * @param query - Persona prompt used to rank and validate discovered people.
-   * @param options - Source response plus hop, breadth, limit, and exclusion controls.
+   * @param options - Optional source response, hop, breadth, limit, and exclusion controls.
    * @returns Response; poll with `get()` and read `structuredResponse` as
    *   {@link EngagementExpansionOutput}.
    */
-  async engagementExpansion(query, options) {
+  async engagementExpansion(query, options = {}) {
     if (!query.trim())
       throw new ValidationError("engagementExpansion requires a non-empty persona query");
-    const params = {
-      expandFromResponse: options?.expandFromResponse
-    };
+    const params = {};
+    if (options.expandFromResponse !== void 0)
+      params.expandFromResponse = options.expandFromResponse;
     if (options?.hops !== void 0)
       params.hops = options.hops;
     if (options?.postsPerHop !== void 0)

package/dist/index.d.cts

@@ -1416,8 +1416,12 @@ interface ContentIntelligenceOutput {
 
 /** Options accepted by {@link ResponsesResource.engagementExpansion}. */
 interface EngagementExpansionOptions {
-    /** Finished content_intelligence response whose saved package seeds the walk. */
-    expandFromResponse: string;
+    /**
+     * Finished response whose saved package seeds the walk. This may be a
+     * content-intelligence or prior engagement-expansion response. Omit it to
+     * collect a seed audience and package from the persona prompt first.
+     */
+    expandFromResponse?: string;
     /**
      * Number of outward rounds to run. At the default limit, collection is
      * approximately 300 credits for one hop and 1,060 for three hops.
@@ -1441,7 +1445,8 @@ interface EngagementExpansionOptions {
 }
 /** Resolved parameters echoed in `structuredResponse.agentParams`. */
 interface EngagementExpansionResolvedParams {
-    expandFromResponse: string;
+    /** Null when the run collected its seed package from the prompt. */
+    expandFromResponse: string | null;
     hops: number;
     postsPerHop?: number | null;
     peoplePerNextHop: number;
@@ -1462,12 +1467,16 @@ interface EngagementExpansionHopStats {
 /** Collection and finalist-history accounting for an expansion run. */
 interface EngagementExpansionStats {
     hopsRun: number;
-    hopsRequested: number;
-    postsPerHop: number;
-    postsPerHopSource: 'requested' | 'derived';
+    /** Absent on an early `empty_package` stop. */
+    hopsRequested?: number;
+    /** Absent on an early `empty_package` stop. */
+    postsPerHop?: number;
+    /** Absent on an early `empty_package` stop. */
+    postsPerHopSource?: 'requested' | 'derived';
     /** Hop collection only; enrichment and validation use standard deep-search economics. */
-    collectionCreditsSpent: number;
-    collectionCreditCeiling: number;
+    collectionCreditsSpent?: number;
+    /** Absent on an early `empty_package` stop. */
+    collectionCreditCeiling?: number;
     stopReason: string;
     perHop: EngagementExpansionHopStats[];
     /** Credits spent loading broader engagement history for finalists. */
@@ -1489,6 +1498,8 @@ interface EngagementExpansionOutput {
     candidates: ValidatedCandidate[];
     criteria?: CriteriaMetadata;
     expansionStats?: EngagementExpansionStats;
+    /** Package used by this run, saved so a later expansion can chain from it. */
+    package?: ContentIntelligencePackage;
     agentParams: EngagementExpansionResolvedParams;
 }
 
@@ -1976,6 +1987,12 @@ interface ValidatedCandidate {
      * 2 for judged/out-of-region, and 0 for unjudged. Tier 1 may exist on older responses.
      */
     rankTier?: 0 | 1 | 2 | 3;
+    /**
+     * Zero-based position in the backend's shipped order. Preserve response
+     * order or sort this field ascending; per-row scores cannot reproduce
+     * diversity reordering exactly.
+     */
+    deliveryRank?: number;
     /** Whether the candidate satisfies the search's location requirement. */
     geoOk?: boolean;
     /** Model's direct answer to the location requirement, when one exists. */
@@ -2005,6 +2022,8 @@ interface ValidatedCandidate {
      * criteria. This is useful for display and auditing but no longer forces a lower rank tier.
      */
     backfilled?: boolean;
+    /** Promoted from the excluded pool so deep validation could issue a real verdict. */
+    promotedToValidation?: boolean;
     /**
      * LinkedIn posts this candidate engaged with (reacted or commented).
      * One entry per post — if someone engaged with multiple competitor posts,
@@ -2123,7 +2142,7 @@ interface StructuredResponse extends Record<string, any> {
     /** Competitor rep engagement output (when using competitor_rep_engagement agent) */
     resolutionWarnings?: string[];
     repEngagementStats?: RepEngagementStats;
-    /** Content intelligence output (when using content_intelligence agent). */
+    /** Saved content package from content_intelligence or engagement_expansion. */
     package?: ContentIntelligencePackage;
     summary?: ContentIntelligenceSummary;
     outputs?: ContentIntelligenceOutputs;
@@ -6672,21 +6691,23 @@ declare class ResponsesResource {
      */
     contentIntelligence(query: string, options?: ContentIntelligenceOptions): Promise<CreateResponseResponse>;
     /**
-     * Find new people by walking outward from a saved content-intelligence package.
+     * Find new people by walking outward from a saved engagement package.
      *
-     * Hop 1 pulls the other engagers of the package's best posts. Additional hops
-     * select the highest-fit new people, rank posts from their feeds, and pull the
-     * engagers of those posts. Collection breadth is derived from `limit` unless
-     * `postsPerHop` is set explicitly. At the default limit, collection is about
-     * 300 credits for one hop and 1,060 for three hops; enrichment and validation
-     * use the standard deep-search economics on top.
+     * With `expandFromResponse`, hop 1 pulls the other engagers of that response's
+     * saved package. Without it, the backend first finds a seed audience from the
+     * prompt, collects and saves its package, then expands it. Additional hops
+     * select the highest-fit new people, rank posts from their feeds, and pull
+     * their engagers. Collection breadth is derived from `limit` unless
+     * `postsPerHop` is explicit. At the default limit, hop collection is about
+     * 300 credits for one hop and 1,060 for three; prompt-only seed collection,
+     * enrichment, and validation are additional.
      *
      * @param query - Persona prompt used to rank and validate discovered people.
-     * @param options - Source response plus hop, breadth, limit, and exclusion controls.
+     * @param options - Optional source response, hop, breadth, limit, and exclusion controls.
      * @returns Response; poll with `get()` and read `structuredResponse` as
      *   {@link EngagementExpansionOutput}.
      */
-    engagementExpansion(query: string, options: EngagementExpansionOptions): Promise<CreateResponseResponse>;
+    engagementExpansion(query: string, options?: EngagementExpansionOptions): Promise<CreateResponseResponse>;
     /**
      * Score people who reacted to or commented on competitor LinkedIn posts.
      *

package/dist/index.d.mts

@@ -1416,8 +1416,12 @@ interface ContentIntelligenceOutput {
 
 /** Options accepted by {@link ResponsesResource.engagementExpansion}. */
 interface EngagementExpansionOptions {
-    /** Finished content_intelligence response whose saved package seeds the walk. */
-    expandFromResponse: string;
+    /**
+     * Finished response whose saved package seeds the walk. This may be a
+     * content-intelligence or prior engagement-expansion response. Omit it to
+     * collect a seed audience and package from the persona prompt first.
+     */
+    expandFromResponse?: string;
     /**
      * Number of outward rounds to run. At the default limit, collection is
      * approximately 300 credits for one hop and 1,060 for three hops.
@@ -1441,7 +1445,8 @@ interface EngagementExpansionOptions {
 }
 /** Resolved parameters echoed in `structuredResponse.agentParams`. */
 interface EngagementExpansionResolvedParams {
-    expandFromResponse: string;
+    /** Null when the run collected its seed package from the prompt. */
+    expandFromResponse: string | null;
     hops: number;
     postsPerHop?: number | null;
     peoplePerNextHop: number;
@@ -1462,12 +1467,16 @@ interface EngagementExpansionHopStats {
 /** Collection and finalist-history accounting for an expansion run. */
 interface EngagementExpansionStats {
     hopsRun: number;
-    hopsRequested: number;
-    postsPerHop: number;
-    postsPerHopSource: 'requested' | 'derived';
+    /** Absent on an early `empty_package` stop. */
+    hopsRequested?: number;
+    /** Absent on an early `empty_package` stop. */
+    postsPerHop?: number;
+    /** Absent on an early `empty_package` stop. */
+    postsPerHopSource?: 'requested' | 'derived';
     /** Hop collection only; enrichment and validation use standard deep-search economics. */
-    collectionCreditsSpent: number;
-    collectionCreditCeiling: number;
+    collectionCreditsSpent?: number;
+    /** Absent on an early `empty_package` stop. */
+    collectionCreditCeiling?: number;
     stopReason: string;
     perHop: EngagementExpansionHopStats[];
     /** Credits spent loading broader engagement history for finalists. */
@@ -1489,6 +1498,8 @@ interface EngagementExpansionOutput {
     candidates: ValidatedCandidate[];
     criteria?: CriteriaMetadata;
     expansionStats?: EngagementExpansionStats;
+    /** Package used by this run, saved so a later expansion can chain from it. */
+    package?: ContentIntelligencePackage;
     agentParams: EngagementExpansionResolvedParams;
 }
 
@@ -1976,6 +1987,12 @@ interface ValidatedCandidate {
      * 2 for judged/out-of-region, and 0 for unjudged. Tier 1 may exist on older responses.
      */
     rankTier?: 0 | 1 | 2 | 3;
+    /**
+     * Zero-based position in the backend's shipped order. Preserve response
+     * order or sort this field ascending; per-row scores cannot reproduce
+     * diversity reordering exactly.
+     */
+    deliveryRank?: number;
     /** Whether the candidate satisfies the search's location requirement. */
     geoOk?: boolean;
     /** Model's direct answer to the location requirement, when one exists. */
@@ -2005,6 +2022,8 @@ interface ValidatedCandidate {
      * criteria. This is useful for display and auditing but no longer forces a lower rank tier.
      */
     backfilled?: boolean;
+    /** Promoted from the excluded pool so deep validation could issue a real verdict. */
+    promotedToValidation?: boolean;
     /**
      * LinkedIn posts this candidate engaged with (reacted or commented).
      * One entry per post — if someone engaged with multiple competitor posts,
@@ -2123,7 +2142,7 @@ interface StructuredResponse extends Record<string, any> {
     /** Competitor rep engagement output (when using competitor_rep_engagement agent) */
     resolutionWarnings?: string[];
     repEngagementStats?: RepEngagementStats;
-    /** Content intelligence output (when using content_intelligence agent). */
+    /** Saved content package from content_intelligence or engagement_expansion. */
     package?: ContentIntelligencePackage;
     summary?: ContentIntelligenceSummary;
     outputs?: ContentIntelligenceOutputs;
@@ -6672,21 +6691,23 @@ declare class ResponsesResource {
      */
     contentIntelligence(query: string, options?: ContentIntelligenceOptions): Promise<CreateResponseResponse>;
     /**
-     * Find new people by walking outward from a saved content-intelligence package.
+     * Find new people by walking outward from a saved engagement package.
      *
-     * Hop 1 pulls the other engagers of the package's best posts. Additional hops
-     * select the highest-fit new people, rank posts from their feeds, and pull the
-     * engagers of those posts. Collection breadth is derived from `limit` unless
-     * `postsPerHop` is set explicitly. At the default limit, collection is about
-     * 300 credits for one hop and 1,060 for three hops; enrichment and validation
-     * use the standard deep-search economics on top.
+     * With `expandFromResponse`, hop 1 pulls the other engagers of that response's
+     * saved package. Without it, the backend first finds a seed audience from the
+     * prompt, collects and saves its package, then expands it. Additional hops
+     * select the highest-fit new people, rank posts from their feeds, and pull
+     * their engagers. Collection breadth is derived from `limit` unless
+     * `postsPerHop` is explicit. At the default limit, hop collection is about
+     * 300 credits for one hop and 1,060 for three; prompt-only seed collection,
+     * enrichment, and validation are additional.
      *
      * @param query - Persona prompt used to rank and validate discovered people.
-     * @param options - Source response plus hop, breadth, limit, and exclusion controls.
+     * @param options - Optional source response, hop, breadth, limit, and exclusion controls.
      * @returns Response; poll with `get()` and read `structuredResponse` as
      *   {@link EngagementExpansionOutput}.
      */
-    engagementExpansion(query: string, options: EngagementExpansionOptions): Promise<CreateResponseResponse>;
+    engagementExpansion(query: string, options?: EngagementExpansionOptions): Promise<CreateResponseResponse>;
     /**
      * Score people who reacted to or commented on competitor LinkedIn posts.
      *

package/dist/index.d.ts

@@ -1416,8 +1416,12 @@ interface ContentIntelligenceOutput {
 
 /** Options accepted by {@link ResponsesResource.engagementExpansion}. */
 interface EngagementExpansionOptions {
-    /** Finished content_intelligence response whose saved package seeds the walk. */
-    expandFromResponse: string;
+    /**
+     * Finished response whose saved package seeds the walk. This may be a
+     * content-intelligence or prior engagement-expansion response. Omit it to
+     * collect a seed audience and package from the persona prompt first.
+     */
+    expandFromResponse?: string;
     /**
      * Number of outward rounds to run. At the default limit, collection is
      * approximately 300 credits for one hop and 1,060 for three hops.
@@ -1441,7 +1445,8 @@ interface EngagementExpansionOptions {
 }
 /** Resolved parameters echoed in `structuredResponse.agentParams`. */
 interface EngagementExpansionResolvedParams {
-    expandFromResponse: string;
+    /** Null when the run collected its seed package from the prompt. */
+    expandFromResponse: string | null;
     hops: number;
     postsPerHop?: number | null;
     peoplePerNextHop: number;
@@ -1462,12 +1467,16 @@ interface EngagementExpansionHopStats {
 /** Collection and finalist-history accounting for an expansion run. */
 interface EngagementExpansionStats {
     hopsRun: number;
-    hopsRequested: number;
-    postsPerHop: number;
-    postsPerHopSource: 'requested' | 'derived';
+    /** Absent on an early `empty_package` stop. */
+    hopsRequested?: number;
+    /** Absent on an early `empty_package` stop. */
+    postsPerHop?: number;
+    /** Absent on an early `empty_package` stop. */
+    postsPerHopSource?: 'requested' | 'derived';
     /** Hop collection only; enrichment and validation use standard deep-search economics. */
-    collectionCreditsSpent: number;
-    collectionCreditCeiling: number;
+    collectionCreditsSpent?: number;
+    /** Absent on an early `empty_package` stop. */
+    collectionCreditCeiling?: number;
     stopReason: string;
     perHop: EngagementExpansionHopStats[];
     /** Credits spent loading broader engagement history for finalists. */
@@ -1489,6 +1498,8 @@ interface EngagementExpansionOutput {
     candidates: ValidatedCandidate[];
     criteria?: CriteriaMetadata;
     expansionStats?: EngagementExpansionStats;
+    /** Package used by this run, saved so a later expansion can chain from it. */
+    package?: ContentIntelligencePackage;
     agentParams: EngagementExpansionResolvedParams;
 }
 
@@ -1976,6 +1987,12 @@ interface ValidatedCandidate {
      * 2 for judged/out-of-region, and 0 for unjudged. Tier 1 may exist on older responses.
      */
     rankTier?: 0 | 1 | 2 | 3;
+    /**
+     * Zero-based position in the backend's shipped order. Preserve response
+     * order or sort this field ascending; per-row scores cannot reproduce
+     * diversity reordering exactly.
+     */
+    deliveryRank?: number;
     /** Whether the candidate satisfies the search's location requirement. */
     geoOk?: boolean;
     /** Model's direct answer to the location requirement, when one exists. */
@@ -2005,6 +2022,8 @@ interface ValidatedCandidate {
      * criteria. This is useful for display and auditing but no longer forces a lower rank tier.
      */
     backfilled?: boolean;
+    /** Promoted from the excluded pool so deep validation could issue a real verdict. */
+    promotedToValidation?: boolean;
     /**
      * LinkedIn posts this candidate engaged with (reacted or commented).
      * One entry per post — if someone engaged with multiple competitor posts,
@@ -2123,7 +2142,7 @@ interface StructuredResponse extends Record<string, any> {
     /** Competitor rep engagement output (when using competitor_rep_engagement agent) */
     resolutionWarnings?: string[];
     repEngagementStats?: RepEngagementStats;
-    /** Content intelligence output (when using content_intelligence agent). */
+    /** Saved content package from content_intelligence or engagement_expansion. */
     package?: ContentIntelligencePackage;
     summary?: ContentIntelligenceSummary;
     outputs?: ContentIntelligenceOutputs;
@@ -6672,21 +6691,23 @@ declare class ResponsesResource {
      */
     contentIntelligence(query: string, options?: ContentIntelligenceOptions): Promise<CreateResponseResponse>;
     /**
-     * Find new people by walking outward from a saved content-intelligence package.
+     * Find new people by walking outward from a saved engagement package.
      *
-     * Hop 1 pulls the other engagers of the package's best posts. Additional hops
-     * select the highest-fit new people, rank posts from their feeds, and pull the
-     * engagers of those posts. Collection breadth is derived from `limit` unless
-     * `postsPerHop` is set explicitly. At the default limit, collection is about
-     * 300 credits for one hop and 1,060 for three hops; enrichment and validation
-     * use the standard deep-search economics on top.
+     * With `expandFromResponse`, hop 1 pulls the other engagers of that response's
+     * saved package. Without it, the backend first finds a seed audience from the
+     * prompt, collects and saves its package, then expands it. Additional hops
+     * select the highest-fit new people, rank posts from their feeds, and pull
+     * their engagers. Collection breadth is derived from `limit` unless
+     * `postsPerHop` is explicit. At the default limit, hop collection is about
+     * 300 credits for one hop and 1,060 for three; prompt-only seed collection,
+     * enrichment, and validation are additional.
      *
      * @param query - Persona prompt used to rank and validate discovered people.
-     * @param options - Source response plus hop, breadth, limit, and exclusion controls.
+     * @param options - Optional source response, hop, breadth, limit, and exclusion controls.
      * @returns Response; poll with `get()` and read `structuredResponse` as
      *   {@link EngagementExpansionOutput}.
      */
-    engagementExpansion(query: string, options: EngagementExpansionOptions): Promise<CreateResponseResponse>;
+    engagementExpansion(query: string, options?: EngagementExpansionOptions): Promise<CreateResponseResponse>;
     /**
      * Score people who reacted to or commented on competitor LinkedIn posts.
      *

package/dist/index.mjs

@@ -3396,9 +3396,9 @@ class ResponsesResource {
       "expandFromResponse",
       "expand_from_response"
     );
-    if (typeof expandFromResponse !== "string" || !expandFromResponse.trim()) {
+    if (expandFromResponse !== void 0 && (typeof expandFromResponse !== "string" || !expandFromResponse.trim())) {
       throw new ValidationError(
-        "expandFromResponse is required for engagement_expansion and must be a non-empty string"
+        "expandFromResponse must be a non-empty string when provided for engagement_expansion"
       );
     }
     for (const [camel, snake] of [
@@ -3880,26 +3880,28 @@ class ResponsesResource {
     });
   }
   /**
-   * Find new people by walking outward from a saved content-intelligence package.
+   * Find new people by walking outward from a saved engagement package.
    *
-   * Hop 1 pulls the other engagers of the package's best posts. Additional hops
-   * select the highest-fit new people, rank posts from their feeds, and pull the
-   * engagers of those posts. Collection breadth is derived from `limit` unless
-   * `postsPerHop` is set explicitly. At the default limit, collection is about
-   * 300 credits for one hop and 1,060 for three hops; enrichment and validation
-   * use the standard deep-search economics on top.
+   * With `expandFromResponse`, hop 1 pulls the other engagers of that response's
+   * saved package. Without it, the backend first finds a seed audience from the
+   * prompt, collects and saves its package, then expands it. Additional hops
+   * select the highest-fit new people, rank posts from their feeds, and pull
+   * their engagers. Collection breadth is derived from `limit` unless
+   * `postsPerHop` is explicit. At the default limit, hop collection is about
+   * 300 credits for one hop and 1,060 for three; prompt-only seed collection,
+   * enrichment, and validation are additional.
    *
    * @param query - Persona prompt used to rank and validate discovered people.
-   * @param options - Source response plus hop, breadth, limit, and exclusion controls.
+   * @param options - Optional source response, hop, breadth, limit, and exclusion controls.
    * @returns Response; poll with `get()` and read `structuredResponse` as
    *   {@link EngagementExpansionOutput}.
    */
-  async engagementExpansion(query, options) {
+  async engagementExpansion(query, options = {}) {
     if (!query.trim())
       throw new ValidationError("engagementExpansion requires a non-empty persona query");
-    const params = {
-      expandFromResponse: options?.expandFromResponse
-    };
+    const params = {};
+    if (options.expandFromResponse !== void 0)
+      params.expandFromResponse = options.expandFromResponse;
     if (options?.hops !== void 0)
       params.hops = options.hops;
     if (options?.postsPerHop !== void 0)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lumnisai",
   "type": "module",
-  "version": "0.5.33",
+  "version": "0.5.34",
   "description": "Official Node.js SDK for the Lumnis AI API",
   "author": "Lumnis AI",
   "license": "MIT",