@scenario-labs/sdk 3.2.0 → 3.3.0

package/src/lib/query.ts

@@ -0,0 +1,42 @@
+import type { FinalRequestOptions } from '../internal/request-options';
+
+/**
+ * Keep unset query values from erasing the client's `defaultQuery`.
+ *
+ * Generated methods build their typed query with every key, set or not:
+ * `{ dryRun, projectId, ...options?.query }` yields `projectId: undefined` when
+ * the caller did not pass one. `buildURL` then spreads that object over the
+ * client's `defaultQuery`, so the unset key erases the client-level `projectId`
+ * and the request goes out unscoped — the API then falls back to the team's
+ * default project.
+ *
+ * So, on a new object (the query may be the caller's own params object):
+ * - `undefined` is dropped everywhere (the query serializer skips it anyway);
+ * - `null` and `''` are dropped only for keys `defaultQuery` provides, so the
+ *   default applies. Elsewhere they keep their usual serialization (`key=`).
+ *
+ * Called from the enhanced client's `prepareOptions`, i.e. on every request
+ * (retries included — it is idempotent).
+ */
+export function normalizeQuery(
+  options: FinalRequestOptions,
+  defaultQuery: Record<string, unknown> | undefined,
+): void {
+  const query = options.query;
+  // Only plain objects: rebuilding a URLSearchParams, a Map or a class instance
+  // from its own enumerable entries would silently empty it.
+  if (typeof query !== 'object' || query === null) return;
+  const proto = Object.getPrototypeOf(query);
+  if (proto !== Object.prototype && proto !== null) return;
+  options.query = Object.fromEntries(
+    Object.entries(query).filter(
+      ([key, value]) =>
+        value !== undefined &&
+        !(
+          defaultQuery &&
+          Object.prototype.hasOwnProperty.call(defaultQuery, key) &&
+          (value === null || value === '')
+        ),
+    ),
+  );
+}

package/src/lib/scenario.ts

@@ -1,8 +1,10 @@
 import { Scenario as BaseScenario, type ClientOptions as BaseClientOptions } from '../client';
+import type { FinalRequestOptions } from '../internal/request-options';
 import { EnhancedAssets } from './asset';
 import { EnhancedGenerate } from './generate';
 import { EnhancedJobs } from './job';
 import { EnhancedModels } from './models';
+import { normalizeQuery } from './query';
 import { EnhancedUploads } from './upload';
 import { EnhancedWorkflows } from './workflow';
 
@@ -82,6 +84,12 @@ export class Scenario extends BaseScenario {
     } as BaseClientOptions);
     this.projectId = projectId ?? null;
   }
+
+  /** Keep unset query values from erasing the client's `defaultQuery` (see `./query`). */
+  protected override async prepareOptions(options: FinalRequestOptions): Promise<void> {
+    await super.prepareOptions(options);
+    normalizeQuery(options, this.defaultQuery());
+  }
 }
 
 function stripKey<T extends object>(obj: T | undefined, key: string): Partial<T> | undefined {

package/src/lib/scope.ts

@@ -26,15 +26,50 @@ export function extractScope(options?: RequestOptions): Scope | undefined {
   return { projectId };
 }
 
+/** Read the typed `projectId` param of a call (`params`, `query` or `body`). Returns `undefined` if absent. */
+export function paramsProjectId(params: unknown): string | undefined {
+  if (!params || typeof params !== 'object') return undefined;
+  const projectId = (params as Record<string, unknown>)['projectId'];
+  return typeof projectId === 'string' && projectId ? projectId : undefined;
+}
+
+/**
+ * The project a request was actually sent to, read from its final options —
+ * the ones `APIResponseProps.options` carries, after the generated method
+ * merged typed params with `options.query` and `prepareOptions` normalized
+ * the query. Its `projectId` if it holds one, else the client default that
+ * `buildURL` merges in; `undefined` with neither (e.g. API-key auth with
+ * implicit scope).
+ *
+ * Reading the request instead of predicting it from params and options keeps
+ * this right whatever the generated merge does. Capture it on enhanced
+ * entities so that follow-up helper calls (`.wait()`, `entity.run()`, ...)
+ * stay in the project the originating request went to.
+ */
+export function sentScope(
+  finalOptions: RequestOptions,
+  clientDefault: string | null | undefined,
+): Scope | undefined {
+  const projectId = extractScope(finalOptions)?.projectId ?? clientDefault;
+  return projectId ? { projectId } : undefined;
+}
+
+/**
+ * Whether a call names its project itself, with a non-empty `projectId` in
+ * its typed params or in `options.query`. Only then must a scope captured
+ * earlier not be replayed over it; an unset value (`undefined`, `null`, `''`,
+ * e.g. from an optional spread) leaves the captured scope in charge.
+ */
+export function hasExplicitProjectId(options: RequestOptions | undefined, params: unknown): boolean {
+  return paramsProjectId(params) !== undefined || extractScope(options) !== undefined;
+}
+
 /**
- * Resolve the effective scope for an outgoing call:
- *   1. If the per-call options carry a `projectId` query — use that (the explicit override wins).
- *   2. Otherwise, fall back to the client's default `projectId`.
- *   3. If neither is set (e.g. API-key auth with implicit scope), return `undefined`.
+ * Two-tier resolution (`options.query.projectId`, else a fallback) that
+ * ignores typed params.
  *
- * Returns the snapshot we want to *capture on an enhanced entity* so that
- * follow-up helper calls (`.wait()`, `entity.run()`, ...) reuse the same
- * scope and stay in sync with the call that produced them.
+ * @deprecated Predicts the scope instead of reading it from the request.
+ * Use {@link sentScope} on the final request options.
  */
 export function effectiveScope(
   options: RequestOptions | undefined,

package/src/lib/upload.ts

@@ -12,7 +12,7 @@ import {
 } from '../resources/uploads';
 import type { AssetRetrieveResponse } from '../resources/assets/assets';
 import type { ModelRetrieveResponse } from '../resources/models/models';
-import { type Scope, clientProjectId, effectiveScope, withScope } from './scope';
+import { type Scope, clientProjectId, sentScope, withScope } from './scope';
 
 type UploadKind = NonNullable<UploadCreateParams['kind']>;
 
@@ -149,12 +149,14 @@ export type WithUpload<T extends { upload: unknown }> = T & { upload: UploadMeth
 export function enhanceUpload<T extends { upload: { id: string; status: string } }>(
   client: Scenario,
   promise: APIPromise<T>,
-  options?: RequestOptions,
 ): APIPromise<WithUpload<T>> {
-  const scope = effectiveScope(options, clientProjectId(client));
-  return promise._thenUnwrap((data) => ({
+  return promise._thenUnwrap((data, props) => ({
     ...data,
-    upload: Upload.from(client, data.upload as UploadRetrieveResponse['upload'], scope),
+    upload: Upload.from(
+      client,
+      data.upload as UploadRetrieveResponse['upload'],
+      sentScope(props.options, clientProjectId(client)),
+    ),
   }));
 }
 
@@ -170,7 +172,7 @@ export class EnhancedUploads extends Uploads {
     body: UploadCreateParams,
     options?: RequestOptions,
   ): APIPromise<WithUpload<UploadCreateResponse>> {
-    return enhanceUpload(this._client, super.create(body, options), options);
+    return enhanceUpload(this._client, super.create(body, options));
   }
 
   override retrieve(
@@ -178,7 +180,7 @@ export class EnhancedUploads extends Uploads {
     query: UploadRetrieveParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<WithUpload<UploadRetrieveResponse>> {
-    return enhanceUpload(this._client, super.retrieve(uploadID, query, options), options);
+    return enhanceUpload(this._client, super.retrieve(uploadID, query, options));
   }
 
   override triggerAction(
@@ -186,7 +188,7 @@ export class EnhancedUploads extends Uploads {
     body: UploadTriggerActionParams,
     options?: RequestOptions,
   ): APIPromise<WithUpload<UploadTriggerActionResponse>> {
-    return enhanceUpload(this._client, super.triggerAction(uploadID, body, options), options);
+    return enhanceUpload(this._client, super.triggerAction(uploadID, body, options));
   }
 
   /**

package/src/lib/workflow.ts

@@ -10,7 +10,7 @@ import {
   type WorkflowRunResponse,
 } from '../resources/workflows';
 import { type WithJob, enhanceJob } from './job';
-import { type Scope, effectiveScope, withScope } from './scope';
+import { type Scope, hasExplicitProjectId, sentScope, withScope } from './scope';
 import { validateWorkflowFlow } from './workflow_validator';
 // Type-only import to break the circular `scenario.ts` ↔ `workflow.ts` graph at runtime.
 import type { Scenario } from './scenario';
@@ -72,7 +72,10 @@ export class WorkflowEntity {
     params: WorkflowRunParams,
     options?: RequestOptions,
   ): APIPromise<WithJob<WorkflowRunResponse>> {
-    return this._client.workflows.run(this.id, params, withScope(this._scope, options));
+    // The captured scope is only a fallback: an explicit `params.projectId` or
+    // `options.query.projectId` on this call wins.
+    const scope = hasExplicitProjectId(options, params) ? undefined : this._scope;
+    return this._client.workflows.run(this.id, params, withScope(scope, options));
   }
 
   /** @internal Create a WorkflowEntity from raw workflow data, optionally remembering the originating scope. */
@@ -109,10 +112,9 @@ export class EnhancedWorkflows extends Workflows {
     options?: RequestOptions,
   ): APIPromise<EnhancedWorkflowRetrieveResponse> {
     const client = this._client as Scenario;
-    const scope = effectiveScope(options, client.projectId);
-    return super.retrieve(workflowID, query, options)._thenUnwrap((data) => ({
+    return super.retrieve(workflowID, query, options)._thenUnwrap((data, props) => ({
       ...data,
-      workflow: WorkflowEntity.from(client, data.workflow, scope),
+      workflow: WorkflowEntity.from(client, data.workflow, sentScope(props.options, client.projectId)),
     }));
   }
 
@@ -122,7 +124,7 @@ export class EnhancedWorkflows extends Workflows {
     params: WorkflowRunParams,
     options?: RequestOptions,
   ): APIPromise<WithJob<WorkflowRunResponse>> {
-    return enhanceJob(this._client, super.run(workflowID, params, options), options);
+    return enhanceJob(this._client, super.run(workflowID, params, options));
   }
 
   /** Approve a user approval node. Returns an enhanced response where `job` has `.wait()`. */
@@ -131,6 +133,6 @@ export class EnhancedWorkflows extends Workflows {
     body: WorkflowApproveUserParams,
     options?: RequestOptions,
   ): APIPromise<WithJob<WorkflowUserApprovalResponse>> {
-    return enhanceJob(this._client, super.userApproval(workflowID, body, options), options);
+    return enhanceJob(this._client, super.userApproval(workflowID, body, options));
   }
 }

package/src/lib/workflow_validator.ts

@@ -18,6 +18,7 @@ const USER_SELECTION_INPUT_TYPES = new Set(['file_array', 'string_array']);
 
 type RawRef = {
   node?: unknown;
+  equal?: unknown;
   conditional?: unknown;
 };
 
@@ -63,6 +64,11 @@ type RawNode = {
  *       - input ref.node (excluding "workflow" which is a reserved keyword)
  *       - input ref.conditional entries
  *       - loopBodyNodeIds entries
+ *  6. A node an if-else branch can skip is read through a plain `ref.node` only by nodes
+ *     gated by the same branch. A node is skippable when it has a `connection` input on that
+ *     branch, or when every target of one of its `ref.conditional` inputs is skippable on it.
+ *     Any other reader never resolves when the branch is not taken, and the workflow job
+ *     never completes. A `ref.conditional` merge reads whichever branch ran, so it is allowed.
  */
 export function validateWorkflowFlow(flow: unknown[]): void {
   const nodeIds = new Set<string>();
@@ -143,6 +149,115 @@ export function validateWorkflowFlow(flow: unknown[]): void {
       }
     }
   }
+
+  // Pass 3 — readers of branch-gated nodes must be gated by the same branch
+  const branchGates = collectBranchGates(flow as RawNode[]);
+  if (branchGates.size === 0) return;
+
+  for (const rawNode of flow) {
+    const node = rawNode as RawNode;
+    const nodeId = node.id as string;
+    if (!Array.isArray(node.inputs)) continue;
+    const readerGates = branchGates.get(nodeId);
+
+    for (const { inputName, refNode } of collectPlainRefs(node.inputs as RawInput[])) {
+      const producerGates = branchGates.get(refNode);
+      if (!producerGates) continue;
+      const missing = [...producerGates].find((gate) => !readerGates?.has(gate));
+      if (missing) {
+        throw new Error(
+          `Node "${nodeId}" input "${inputName}" reads node "${refNode}", which the if-else branch ${missing} can skip, ` +
+            `but "${nodeId}" is not gated by that branch, so it would never run and the workflow job would never complete. ` +
+            `Gate "${nodeId}" through the same branch, or merge the branches with a conditional ref.`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Maps each node an if-else branch can skip to its gates, formatted as `"<ifElseId>" == "<value>"`.
+ * Direct gates come from `connection` inputs. A `ref.conditional` input whose targets all share a
+ * gate is skipped with them, so its node inherits the shared gates, through chains too.
+ */
+function collectBranchGates(flow: RawNode[]): Map<string, Set<string>> {
+  const ifElseIds = new Set(
+    flow.filter((n) => n.type === 'logic' && n.logicType === 'if-else').map((n) => n.id as string),
+  );
+  const gates = new Map<string, Set<string>>();
+  if (ifElseIds.size === 0) return gates;
+
+  for (const node of flow) {
+    if (!Array.isArray(node.inputs)) continue;
+    for (const input of node.inputs as RawInput[]) {
+      const ref = input.ref;
+      if (input.type !== 'connection' || typeof ref?.node !== 'string' || !ifElseIds.has(ref.node)) continue;
+      const gate = `"${ref.node}" == "${String(ref.equal)}"`;
+      const nodeGates = gates.get(node.id as string) ?? new Set<string>();
+      nodeGates.add(gate);
+      gates.set(node.id as string, nodeGates);
+    }
+  }
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const node of flow) {
+      if (!Array.isArray(node.inputs)) continue;
+      for (const targets of collectConditionalRefs(node.inputs as RawInput[])) {
+        const targetGates = targets.map((id) => gates.get(id));
+        if (targetGates.length === 0 || targetGates.some((g) => !g)) continue;
+        const [first, ...rest] = targetGates as Set<string>[];
+        const shared = [...first!].filter((gate) => rest.every((g) => g.has(gate)));
+        const nodeGates = gates.get(node.id as string) ?? new Set<string>();
+        for (const gate of shared) {
+          if (!nodeGates.has(gate)) {
+            nodeGates.add(gate);
+            changed = true;
+          }
+        }
+        if (nodeGates.size > 0) gates.set(node.id as string, nodeGates);
+      }
+    }
+  }
+  return gates;
+}
+
+/** Target lists of a node's `ref.conditional` inputs, INPUTS_ARRAY sub-inputs included. */
+function collectConditionalRefs(inputs: RawInput[]): string[][] {
+  const lists: string[][] = [];
+  for (const input of inputs) {
+    const conditional = input.ref?.conditional;
+    if (Array.isArray(conditional)) {
+      lists.push(conditional.filter((id): id is string => typeof id === 'string'));
+    }
+    if (Array.isArray(input.items)) {
+      for (const item of input.items) {
+        if (Array.isArray(item)) lists.push(...collectConditionalRefs(item as RawInput[]));
+      }
+    }
+  }
+  return lists;
+}
+
+/** Plain `ref.node` data refs of a node's inputs, INPUTS_ARRAY sub-inputs included; `connection` inputs excluded. */
+function collectPlainRefs(inputs: RawInput[]): Array<{ inputName: string; refNode: string }> {
+  const refs: Array<{ inputName: string; refNode: string }> = [];
+  for (const input of inputs) {
+    const refNode = input.ref?.node;
+    if (input.type !== 'connection' && typeof refNode === 'string' && refNode !== 'workflow') {
+      refs.push({
+        inputName: typeof input.name === 'string' && input.name ? input.name : '(unnamed)',
+        refNode,
+      });
+    }
+    if (Array.isArray(input.items)) {
+      for (const item of input.items) {
+        if (Array.isArray(item)) refs.push(...collectPlainRefs(item as RawInput[]));
+      }
+    }
+  }
+  return refs;
 }
 
 function validateInputRefs(nodeId: string, input: RawInput, nodeIds: Set<string>): void {