deepline 0.2.70 → 0.2.72

package/dist/bundling-sources/sdk/src/client.ts

@@ -1156,16 +1156,16 @@ function isPrebuiltPlayDescription(
 function preferPrebuiltPlayDescriptions<T extends PlayDescription>(
   plays: T[],
 ): T[] {
-  const prebuilt: T[] = [];
-  const owned: T[] = [];
-  for (const play of plays) {
-    if (isPrebuiltPlayDescription(play)) {
-      prebuilt.push(play);
-    } else {
-      owned.push(play);
-    }
-  }
-  return [...prebuilt, ...owned];
+  return plays
+    .map((play, index) => ({ play, index }))
+    .sort(
+      (left, right) =>
+        Number(right.play.pinned) - Number(left.play.pinned) ||
+        Number(isPrebuiltPlayDescription(right.play)) -
+          Number(isPrebuiltPlayDescription(left.play)) ||
+        left.index - right.index,
+    )
+    .map(({ play }) => play);
 }
 
 function isPlayRunPackage(value: unknown): value is PlayRunPackage {
@@ -1775,6 +1775,8 @@ export class DeeplineClient {
       ...(play.reference ? { reference: play.reference } : {}),
       ...(play.displayName ? { displayName: play.displayName } : {}),
       ...(description ? { description } : {}),
+      pinned: Boolean(play.pinned),
+      toolCategories: play.toolCategories ?? [],
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -3778,9 +3780,24 @@ export class DeeplineClient {
     origin?: 'prebuilt' | 'owned';
     grep?: string;
     grepMode?: 'all' | 'any' | 'phrase';
+    categories?: string | string[];
+    includeToolCategories?: boolean;
+    includeArchived?: boolean;
   }): Promise<PlayListItem[]> {
     const params = new URLSearchParams();
     if (options?.origin) params.set('origin', options.origin);
+    if (options?.categories) {
+      params.set(
+        'categories',
+        Array.isArray(options.categories)
+          ? options.categories.join(',')
+          : options.categories,
+      );
+    }
+    if (options?.categories || options?.includeToolCategories) {
+      params.set('include_tool_categories', '1');
+    }
+    if (options?.includeArchived) params.set('include_archived', '1');
     if (options?.grep?.trim()) {
       params.set('grep', options.grep.trim());
       params.set('grep_mode', options.grepMode ?? 'all');
@@ -3793,6 +3810,16 @@ export class DeeplineClient {
     return response.plays ?? [];
   }
 
+  /** Set whether an org-owned Play sorts before unpinned Plays. */
+  async setPlayPinned(
+    playName: string,
+    pinned: boolean,
+  ): Promise<{ name: string; pinned: boolean }> {
+    return this.http.post(`/api/v2/plays/${encodeURIComponent(playName)}/pin`, {
+      pinned,
+    });
+  }
+
   /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
   async getNotificationSettings(): Promise<ProductNotificationSettings> {
     return this.http.get('/api/v2/settings/notifications');
@@ -3981,9 +4008,15 @@ export class DeeplineClient {
    * console.log(`Total runs: ${detail.play.runCount}`);
    * ```
    */
-  async getPlay(name: string): Promise<PlayDetail> {
+  async getPlay(
+    name: string,
+    options?: { source?: 'working' | 'live' | `version:${number}` },
+  ): Promise<PlayDetail> {
     const encodedName = encodeURIComponent(name);
-    return this.http.get<PlayDetail>(`/api/v2/plays/${encodedName}`);
+    const query = options?.source
+      ? `?include=source&revision=${encodeURIComponent(options.source)}`
+      : '';
+    return this.http.get<PlayDetail>(`/api/v2/plays/${encodedName}${query}`);
   }
 
   /**

package/dist/bundling-sources/sdk/src/release.ts

@@ -183,7 +183,7 @@ export const SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: '0.2.70',
+  version: '0.2.72',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/bundling-sources/sdk/src/types.ts

@@ -1010,6 +1010,10 @@ export interface PlayDefinitionDetail {
   name: string;
   /** Human-friendly display name for UI surfaces. */
   displayName?: string;
+  /** Whether this Play sorts before unpinned Plays. */
+  pinned?: boolean;
+  /** Canonical categories declared by tools used in this Play. */
+  toolCategories?: string[];
   /** Whether this entry comes from the Deepline prebuilt registry or the org-owned catalog. */
   origin?: 'prebuilt' | 'owned';
   /** Ownership class used for permissions and badges. */
@@ -1064,6 +1068,8 @@ export interface PlayListItem {
   name: string;
   displayName?: string;
   description?: string | null;
+  pinned?: boolean;
+  toolCategories?: string[];
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   ownerSlug?: string;
@@ -1135,6 +1141,8 @@ export interface PlayDescription {
   reference?: string;
   displayName?: string;
   description?: string | null;
+  pinned?: boolean;
+  toolCategories?: string[];
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   canEdit?: boolean;
@@ -1192,6 +1200,16 @@ export interface PlayDetail {
   customerDbUrl: string;
   /** Change cursor for incremental sync. */
   deltaCursor: number;
+  /**
+   * Present only when requested through `getPlay(..., { source: ... })`.
+   * `files` is the complete authored source tree, keyed by logical path.
+   */
+  source?: {
+    selector: 'working' | 'live' | `version:${number}`;
+    revision: { id: string; version: number };
+    entryFile: string;
+    files: Record<string, string>;
+  };
 }
 
 export interface ClearPlayHistoryRequest {

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -61,16 +61,60 @@ const liveToolResultListDatasets = new Map<
   PlayDataset<Record<string, unknown>>
 >();
 
-const TARGET_FALLBACK_KEYS: Record<string, readonly RegExp[]> = {
-  email: [/^email$/i, /^address$/i, /email/i],
-  phone: [/^phone$/i, /mobile/i, /phone/i, /telephone/i],
-  linkedin: [/^linkedin_url$/i, /^linkedin$/i, /linkedin/i],
-  company_linkedin_url: [/company.*linkedin/i, /linkedin.*company/i],
-  company_domain: [/^company_domain$/i, /company.*domain/i],
-  company_name: [/^company_name$/i, /company.*name/i],
-  domain: [/^domain$/i, /company_domain/i, /domain/i],
-  status: [/^email_status$/i, /^status$/i],
-  email_status: [/^email_status$/i, /^status$/i],
+/**
+ * Keys that describe a field rather than carry it.
+ *
+ * These sit next to the real value under a similar name, so a substring match
+ * on the target name reaches them as soon as the real field is absent.
+ * `phone_status: "unfound"` is not a phone number and `email_type: "work"` is
+ * not an email address.
+ */
+const DESCRIPTOR_SUFFIX =
+  /_(status|type|score|count|id|verified|valid|confidence|quality|source)$/i;
+
+/** A company-scoped key is never the person-scoped answer. */
+const COMPANY_SCOPED = /company/i;
+
+type TargetFallbackRule = {
+  /** Key names that may carry this target's value. */
+  match: readonly RegExp[];
+  /** Key names that must never be treated as this target's value. */
+  reject?: readonly RegExp[];
+};
+
+const TARGET_FALLBACK_KEYS: Record<string, TargetFallbackRule> = {
+  email: {
+    match: [/^email$/i, /^address$/i, /email/i],
+    reject: [DESCRIPTOR_SUFFIX],
+  },
+  phone: {
+    match: [/^phone$/i, /mobile/i, /phone/i, /telephone/i],
+    reject: [DESCRIPTOR_SUFFIX],
+  },
+  linkedin: {
+    match: [/^linkedin_url$/i, /^linkedin$/i, /linkedin/i],
+    reject: [DESCRIPTOR_SUFFIX, COMPANY_SCOPED],
+  },
+  company_linkedin_url: {
+    match: [/company.*linkedin/i, /linkedin.*company/i],
+    reject: [DESCRIPTOR_SUFFIX],
+  },
+  company_domain: {
+    match: [/^company_domain$/i, /company.*domain/i],
+    reject: [DESCRIPTOR_SUFFIX],
+  },
+  company_name: {
+    match: [/^company_name$/i, /company.*name/i],
+    reject: [DESCRIPTOR_SUFFIX],
+  },
+  domain: {
+    match: [/^domain$/i, /company_domain/i, /domain/i],
+    reject: [DESCRIPTOR_SUFFIX],
+  },
+  // Status targets legitimately want the `_status` keys the suffix rule
+  // rejects elsewhere, so they carry no rejections.
+  status: { match: [/^email_status$/i, /^status$/i] },
+  email_status: { match: [/^email_status$/i, /^status$/i] },
 };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -586,12 +630,13 @@ function findFirstTargetByKey(
   }
   if (!isRecord(result)) return null;
 
-  const patterns = TARGET_FALLBACK_KEYS[target] ?? [
-    new RegExp(`^${target}$`, 'i'),
-  ];
+  const rule: TargetFallbackRule = TARGET_FALLBACK_KEYS[target] ?? {
+    match: [new RegExp(`^${target}$`, 'i')],
+  };
   for (const [key, value] of Object.entries(result)) {
+    if (rule.reject?.some((pattern) => pattern.test(key))) continue;
     if (
-      patterns.some((pattern) => pattern.test(key)) &&
+      rule.match.some((pattern) => pattern.test(key)) &&
       isMeaningfulValue(value)
     ) {
       return { value, path: pathToString([...path, key]) };
@@ -896,6 +941,14 @@ function buildTargets(
       targets[target] = fromMetadata;
       continue;
     }
+    // Declared paths are routinely incomplete against the shape a provider
+    // actually returns (zerobounce declares `result.data.email` and answers
+    // with `address`), so the key scan stays as the rescue. It is bounded by
+    // each target's `reject` rules: the scan runs precisely when the provider
+    // returned no value, which is when a same-named neighbour is most likely
+    // to be a different field. Without those rules a real Wiza miss resolved
+    // `phone` to `phone_status: "unfound"` and `linkedin` to
+    // `company_linkedin`, reporting a company page as the person's profile.
     const fallback = findFirstTargetByKey(result, target);
     if (fallback) {
       targets[target] = fallback;

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -38,7 +38,7 @@ export const PLAY_AUTHORING_CONTRACT_CHANGELOG = [
     changed:
       'Materializes the declared input schema in the admitted snapshot so launch never reparses current source.',
     compatibilityOwner: 'Plays Runtime',
-    newWritesEnd: null,
+    newWritesEnd: '2026-08-19',
     readerRemoval: null,
   },
 ] as const;

package/dist/bundling-sources/shared_libs/plays/bundling/index.ts

@@ -137,6 +137,18 @@ export type PlayBundlingAdapter = {
   warnAboutNonDevelopmentBundling?(filePath: string): void;
 };
 
+type PathRelationshipApi = {
+  relative(from: string, to: string): string;
+  isAbsolute(path: string): boolean;
+  sep: string;
+};
+
+const defaultPathRelationshipApi: PathRelationshipApi = {
+  relative,
+  isAbsolute,
+  sep,
+};
+
 function assertValidExportName(exportName: string): void {
   if (exportName === 'default') return;
   if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(exportName)) {
@@ -207,10 +219,10 @@ function sha256(value: string): string {
 
 function sourceIdentityPath(
   filePath: string,
-  adapter: PlayBundlingAdapter,
+  sourceIdentityRoot: string | undefined,
 ): string {
-  if (!adapter.sourceIdentityRoot) return filePath;
-  const identityRoot = resolve(adapter.sourceIdentityRoot);
+  if (!sourceIdentityRoot) return filePath;
+  const identityRoot = resolve(sourceIdentityRoot);
   const logicalPath = relative(identityRoot, resolve(filePath));
   if (
     !logicalPath ||
@@ -254,8 +266,18 @@ function createPlayWorkspace(entryFile: string): PlayWorkspace {
   };
 }
 
-function isPathInsideDirectory(filePath: string, directory: string): boolean {
-  return filePath === directory || filePath.startsWith(`${directory}/`);
+export function isPathInsideDirectory(
+  filePath: string,
+  directory: string,
+  pathApi: PathRelationshipApi = defaultPathRelationshipApi,
+): boolean {
+  const relationship = pathApi.relative(directory, filePath);
+  return (
+    relationship === '' ||
+    (relationship !== '..' &&
+      !relationship.startsWith(`..${pathApi.sep}`) &&
+      !pathApi.isAbsolute(relationship))
+  );
 }
 
 function assertWithinPlayWorkspace(input: {
@@ -1851,6 +1873,7 @@ async function analyzeSourceGraph(
 ): Promise<SourceGraphAnalysis> {
   const absoluteEntryFile = await normalizeLocalPath(entryFile);
   const workspace = createPlayWorkspace(absoluteEntryFile);
+  const sourceIdentityRoot = adapter.sourceIdentityRoot;
   const localFiles = new Map<string, string>();
   const nodeBuiltins = new Set<string>();
   const packages = new Map<string, string | null>();
@@ -1961,10 +1984,10 @@ async function analyzeSourceGraph(
   const sourceHash = sha256(sourceCode);
   const graphHash = sha256(
     JSON.stringify({
-      entryFile: sourceIdentityPath(absoluteEntryFile, adapter),
+      entryFile: sourceIdentityPath(absoluteEntryFile, sourceIdentityRoot),
       localFiles: [...localFiles.entries()]
         .map(([filePath, contents]) => ({
-          filePath: sourceIdentityPath(filePath, adapter),
+          filePath: sourceIdentityPath(filePath, sourceIdentityRoot),
           hash: sha256(contents),
         }))
         .sort((left, right) => left.filePath.localeCompare(right.filePath)),
@@ -1974,7 +1997,7 @@ async function analyzeSourceGraph(
         .sort((left, right) => left.name.localeCompare(right.name)),
       importedPlayDependencies: [...importedPlayDependencies.values()]
         .map((dependency) => ({
-          filePath: sourceIdentityPath(dependency.filePath, adapter),
+          filePath: sourceIdentityPath(dependency.filePath, sourceIdentityRoot),
           playName: dependency.playName,
         }))
         .sort((left, right) => left.filePath.localeCompare(right.filePath)),
@@ -2199,6 +2222,11 @@ export async function bundlePlayFile(
   const exportName = options.exportName?.trim() || 'default';
   assertValidExportName(exportName);
   const absolutePath = await normalizeLocalPath(filePath);
+  // Keep the existing absolute-path wire format unless a caller explicitly
+  // opts into a logical identity root. Production's deployed checker still
+  // uses absolute paths to reconcile bundled imports; source export normalizes
+  // those paths into a portable tree at the API boundary.
+  const sourceIdentityRoot = adapter.sourceIdentityRoot;
   adapter.warnAboutNonDevelopmentBundling?.(absolutePath);
 
   try {
@@ -2210,6 +2238,19 @@ export async function bundlePlayFile(
     analysis.graphHash = sha256(
       `${analysis.graphHash}\nentry-export:${exportName}\nauthoring-contract-edition:${PLAY_AUTHORING_CONTRACT_EDITION}`,
     );
+    const sourceFiles = Object.fromEntries(
+      Object.entries(analysis.sourceFiles).map(([sourcePath, sourceCode]) => [
+        sourceIdentityPath(sourcePath, sourceIdentityRoot),
+        sourceCode,
+      ]),
+    );
+    const importPolicy: PlayImportPolicy = {
+      ...analysis.importPolicy,
+      localFiles: analysis.importPolicy.localFiles.map((sourcePath) =>
+        sourceIdentityPath(sourcePath, sourceIdentityRoot),
+      ),
+    };
+    const entryFile = sourceIdentityPath(absolutePath, sourceIdentityRoot);
     try {
       validatePlaySourceFilesHaveNoInlineSecrets(analysis.sourceFiles);
     } catch (error) {
@@ -2267,9 +2308,9 @@ export async function bundlePlayFile(
         success: true,
         artifact: {
           ...cachedArtifact,
-          entryFile: absolutePath,
+          entryFile,
           sourceHash: analysis.sourceHash,
-          importPolicy: analysis.importPolicy,
+          importPolicy,
           compatibility: buildPlayContractCompatibility({
             toolErrorSchemaVersion:
               analysis.toolErrorSchemaVersion ?? undefined,
@@ -2277,7 +2318,7 @@ export async function bundlePlayFile(
           cacheHit: true,
         },
         sourceCode: analysis.sourceCode,
-        sourceFiles: analysis.sourceFiles,
+        sourceFiles,
         filePath: absolutePath,
         playName: analysis.playName,
         playDescription: analysis.playDescription,
@@ -2330,7 +2371,7 @@ export async function bundlePlayFile(
     const artifact: PlayBundleArtifact = {
       codeFormat: 'cjs_module',
       artifactKind: target,
-      entryFile: absolutePath,
+      entryFile,
       virtualFilename,
       sourceHash: analysis.sourceHash,
       graphHash: analysis.graphHash,
@@ -2338,7 +2379,7 @@ export async function bundlePlayFile(
       sourceMapHash: sha256(normalizedSourceMap),
       bundledCode: executableCode,
       sourceMap: normalizedSourceMap,
-      importPolicy: analysis.importPolicy,
+      importPolicy,
       compatibility: buildPlayContractCompatibility({
         toolErrorSchemaVersion: analysis.toolErrorSchemaVersion ?? undefined,
       }),
@@ -2352,7 +2393,7 @@ export async function bundlePlayFile(
       success: true,
       artifact,
       sourceCode: analysis.sourceCode,
-      sourceFiles: analysis.sourceFiles,
+      sourceFiles,
       filePath: absolutePath,
       playName: analysis.playName,
       playDescription: analysis.playDescription,

package/dist/bundling-sources/shared_libs/plays/enrich-play-compiler.ts

@@ -691,10 +691,20 @@ export function compileEnrichConfigToPlaySource(
   const runOptionsSource = options.failFast
     ? `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart), onRowError: 'fail' as const }`
     : `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart) }`;
+  const describedColumns = config.commands
+    .filter((command) => isWaterfall(command) || !command.disabled)
+    .map((command) =>
+      (isWaterfall(command) ? command.with_waterfall : command.alias)
+        .replace(/[_-]+/g, ' ')
+        .trim(),
+    )
+    .filter(Boolean)
+    .slice(0, 3);
+  const generatedDescription = describedColumns.length
+    ? `Enrich CSV rows with ${describedColumns.join(', ')}.`
+    : 'Prepare CSV rows for enrichment.';
   const playOptionsSource = [
-    `description: ${stringLiteral(
-      'Read a CSV file, run the configured Deepline enrich commands, and return enriched rows.',
-    )}`,
+    `description: ${stringLiteral(generatedDescription)}`,
     ...(options.maxCreditsPerRun === undefined
       ? []
       : [`billing: { maxCreditsPerRun: ${String(options.maxCreditsPerRun)} }`]),

package/dist/bundling-sources/shared_libs/plays/tool-category-descriptions.ts

@@ -49,3 +49,15 @@ export const TOOL_CATEGORY_DESCRIPTIONS: Readonly<Record<string, string>> = {
 export function describeToolCategory(category: string): string | null {
   return TOOL_CATEGORY_DESCRIPTIONS[category] ?? null;
 }
+
+/** Human-readable label for a canonical tool-category slug. */
+export function formatToolCategoryLabel(category: string): string {
+  const normalized = category
+    .trim()
+    .replace(/[_-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+  return normalized
+    ? `${normalized[0]?.toUpperCase() ?? ''}${normalized.slice(1)}`
+    : '';
+}