Merge pull request #13 from javrrr/override-makeRequired-and-quirks

overrides: add makeRequired DSL + 6 input-shape quirks + 5 service-method JSDocs

Author: javrrr

scripts/generate-types.ts

@@ -35,6 +35,8 @@ interface SchemaOverride {
   note: string;
   /** Fields to relax from required to optional (spec marks them required but the API doesn't). */
   makeOptional?: string[];
+  /** Fields to promote from optional to required (spec marks them optional but the API requires them). */
+  makeRequired?: string[];
   /** Fields whose type should be replaced. Use type names from schemas.ts (not Schemas["..."]). */
   fieldTypes?: Record<string, string>;
   /** Optional fields to add when runtime responses include undocumented properties. */
@@ -56,7 +58,7 @@ interface SchemaOverride {
  */
 const SCHEMA_OVERRIDES: Record<string, SchemaOverride> = {
   DataStreamInputRepresentation: {
-    note: "Spec bugs: dataLakeObjectInfo should accept single or array; mappings and sourceFields are not required for all connector types",
+    note: "Spec bugs: dataLakeObjectInfo should accept single or array; mappings and sourceFields are not required for all connector types. Routing note: dataAccessMode='Direct_Access' is required for federated/BYOL connectors (Snowflake, Databricks, BigQuery, Iceberg) — without it the server returns `400 INTERNAL_ERROR: Unable to post Data Stream: DATA_CONNECTORS is not supported` even when the connector is GA. Direct_Access streams must also OMIT the top-level `datasource` field (otherwise: `DataSource name should be empty for External data streams`); the connection binding is established via connectorInfo.connectorDetails.name instead.",
     makeOptional: ["mappings", "sourceFields"],
     fieldTypes: {
       dataLakeObjectInfo: "DataLakeObjectInputRepresentation | DataLakeObjectInputRepresentation[]",
@@ -81,7 +83,7 @@ const SCHEMA_OVERRIDES: Record<string, SchemaOverride> = {
     },
   },
   SemanticSearchInputRepresentation: {
-    note: "Spec bugs: processingType missing from spec but required by API; attachment/transcribe fields are only required for document/PDF search indexes, not structured DMO search",
+    note: "Spec bugs: processingType missing from spec but required by API; attachment/transcribe fields are only required for document/PDF search indexes, not structured DMO search. Input rejects output-only display-name fields (sourceDmoName, sourceDmoFieldName, relatedDmoName, relatedDmoFieldName) that GET responses include — round-tripping a GET shape into a POST returns `500 UNKNOWN_EXCEPTION` with no diagnostic body. Pass developer-name fields only.",
     makeOptional: [
       "attachmentDmoDeveloperName",
       "transcribeDmoDeveloperName",
@@ -95,6 +97,21 @@ const SCHEMA_OVERRIDES: Record<string, SchemaOverride> = {
       processingType: '"NEAR_REALTIME" | "REALTIME"',
     },
   },
+  ConnectionSchemaFieldInputRepresentation: {
+    note: "Server NPEs (`Cannot invoke java.lang.CharSequence.length() because this.text is null`) when `label` is omitted from any field. Spec marks it optional but the upsert handler dereferences it unconditionally.",
+    makeRequired: ["label"],
+  },
+  DataStreamFieldMappingInputRepresentation: {
+    note: "Asymmetric input/output: POST input uses `sourceFieldLabel`, but GET responses echo `sourceFieldName` for the same field. Round-tripping GET→POST without renaming fails with JSON_PARSER_ERROR. Also: targetFieldReturntype is required by the create handler — when omitted, the mapping is silently dropped from the saved data stream with no error.",
+    makeRequired: ["targetFieldReturntype"],
+  },
+  DataStreamSourceFieldInputRepresentation: {
+    note: "Asymmetric input/output: POST input uses `dataType` (camelCase), but GET responses echo `datatype` (lowercase) for the same field. Round-tripping GET→POST without renaming fails with `JSON_PARSER_ERROR: Unrecognized field 'datatype'`.",
+  },
+  VectorEmbeddingInputRepresentation: {
+    note: "Server NPEs when vectorEmbeddingRelatedFields is omitted, empty, or null. The list must be non-empty (typical minimum: a single entry pointing at the source DMO's primary key). Spec marks it optional.",
+    makeRequired: ["vectorEmbeddingRelatedFields"],
+  },
 };
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -725,13 +742,23 @@ async function main() {
 
   // Step 4: Flatten schemas, apply overrides, and generate discriminated unions
 
-  // Validate overrides reference real schemas
-  for (const name of Object.keys(SCHEMA_OVERRIDES)) {
+  // Validate overrides reference real schemas, and reject contradictions
+  // between makeOptional/makeRequired (a single field appearing in both is
+  // a config error and should fail loudly rather than silently last-wins).
+  for (const [name, override] of Object.entries(SCHEMA_OVERRIDES)) {
     if (!schemas[name]) {
       throw new Error(
         `SCHEMA_OVERRIDES: schema "${name}" not found in spec — remove stale override`,
       );
     }
+    const optional = new Set(override.makeOptional ?? []);
+    for (const field of override.makeRequired ?? []) {
+      if (optional.has(field)) {
+        throw new Error(
+          `SCHEMA_OVERRIDES.${name}: field "${field}" is in both makeOptional and makeRequired`,
+        );
+      }
+    }
   }
 
   // Flatten allOf schemas + schemas with overrides
@@ -741,13 +768,30 @@ async function main() {
     const props = collectFlatProperties(name, schemas, !!override);
     if (!props) continue;
 
-    // Apply overrides
+    // Apply overrides. Each list referencing an existing-field name (the
+    // make* and fieldTypes families) is validated against the flattened
+    // property set — a stale field name fails generation, mirroring the
+    // schema-name validation above. The add*Fields families are skipped
+    // here because they're explicitly for fields NOT yet present.
     if (override) {
+      const validateField = (kind: string, field: string): void => {
+        if (!props[field]) {
+          throw new Error(
+            `SCHEMA_OVERRIDES.${name}.${kind}: field "${field}" not found on schema — remove stale override`,
+          );
+        }
+      };
       for (const field of override.makeOptional ?? []) {
-        if (props[field]) props[field].required = false;
+        validateField("makeOptional", field);
+        props[field]!.required = false;
+      }
+      for (const field of override.makeRequired ?? []) {
+        validateField("makeRequired", field);
+        props[field]!.required = true;
       }
       for (const [field, type] of Object.entries(override.fieldTypes ?? {})) {
-        if (props[field]) props[field].tsType = type;
+        validateField("fieldTypes", field);
+        props[field]!.tsType = type;
       }
       for (const [field, type] of Object.entries(override.addOptionalFields ?? {})) {
         if (!props[field]) {

src/generated/openapi.d.ts

@@ -13215,6 +13215,13 @@ export type components = {
              *     **Available Version:** 60.0
              */
             activationTargetSubjectConfig?: components["schemas"]["ActivationTargetSubjectConfigInputRepresentation"];
+            /**
+             * @description Type of activation. If unspecified, defaults to `Segment`.
+             *
+             *     **Available Version:** 66.0
+             * @enum {string}
+             */
+            activationType?: "ApiTriggered" | "Segment";
             /**
              * @description Limiting expression configuration for the activation.
              *
@@ -13283,7 +13290,7 @@ export type components = {
              */
             limitValue?: number;
             /**
-             * @description Segment ID of the segment the activation needs to be created against. Either marketSegmentId or segmentApiName must be present.
+             * @description Segment ID of the segment the activation needs to be created against. Either marketSegmentId or segmentApiName must be present. Exclude this property for `ApiTriggered` activation types.
              *
              *     **Available Version:** 60.0
              */
@@ -13307,7 +13314,7 @@ export type components = {
              */
             relatedDmoFiltersConfig?: components["schemas"]["DMOFilterConfigInputRepresentation"][];
             /**
-             * @description Developer name of the segment. Either marketSegmentId or segmentApiName must be present.
+             * @description Developer name of the segment. Either marketSegmentId or segmentApiName must be present. Exclude this property for `ApiTriggered` activation types.
              *
              *     **Available Version:** 60.0
              */
@@ -13324,6 +13331,12 @@ export type components = {
              *     **Available Version:** 60.0
              */
             shouldExcludeUpdates?: boolean;
+            /**
+             * @description Developer name of the source DMO. Required for `ApiTriggered` activation types. Exclude this property for `Segment` activation types.
+             *
+             *     **Available Version:** 66.0
+             */
+            sourceDmoName?: string;
             /**
              * @description Configuration of static data, which adds metadata or campaign details in the output. For example, `campaignId` or `campaignName`.
              *
@@ -28525,6 +28538,15 @@ export type components = {
              *     **Available Version:** 60.0
              */
             activationTargetSubjectConfig: components["schemas"]["ActivationTargetSubjectRepresentation"];
+            /**
+             * @description Type of activation.
+             *
+             *     **Filter Group:** Small
+             *
+             *     **Available Version:** 66.0
+             * @enum {string}
+             */
+            activationType?: "ApiTriggered" | "Segment";
             /**
              * @description Limiting expression configuration for the activation.
              *
@@ -28696,7 +28718,7 @@ export type components = {
              */
             limitValue?: number;
             /**
-             * @description Segment ID of the activation.
+             * @description Segment ID of the activation. Returned for `Segment` type activations.
              *
              *     **Filter Group:** Small
              *
@@ -28737,15 +28759,15 @@ export type components = {
              */
             relatedDmoFiltersConfig?: components["schemas"]["DmoFiltersConfigRepresentation"];
             /**
-             * @description Segment API name.
+             * @description Segment API name. Returned for `Segment` type activations.
              *
              *     **Filter Group:** Small
              *
              *     **Available Version:** 60.0
              */
             segmentApiName?: string;
             /**
-             * @description Segment ID of the activation.
+             * @description Segment ID of the activation. Returned for `Segment` type activations.
              *
              *     **Filter Group:** Small
              *
@@ -28768,6 +28790,14 @@ export type components = {
              *     **Available Version:** 60.0
              */
             shouldExcludeUpdates?: boolean;
+            /**
+             * @description Developer name of the source DMO.
+             *
+             *     **Filter Group:** Small
+             *
+             *     **Available Version:** 66.0
+             */
+            sourceDmoName?: string;
             /**
              * @description Static data configuration for the activation.
              *

src/generated/openapi.yaml

@@ -8746,6 +8746,15 @@ components:
                 **Available Version:** 60.0
               allOf:
                 - $ref: "#/components/schemas/ActivationTargetSubjectConfigInputRepresentation"
+            activationType:
+              description: |
+                Type of activation. If unspecified, defaults to `Segment`.
+
+                **Available Version:** 66.0
+              type: string
+              enum:
+                - ApiTriggered
+                - Segment
             attributeLimitingExpressionConfig:
               description: |
                 Limiting expression configuration for the activation.
@@ -8828,7 +8837,7 @@ components:
               type: integer
             marketSegmentId:
               description: |
-                Segment ID of the segment the activation needs to be created against. Either marketSegmentId or segmentApiName must be present.
+                Segment ID of the segment the activation needs to be created against. Either marketSegmentId or segmentApiName must be present. Exclude this property for `ApiTriggered` activation types.
 
                 **Available Version:** 60.0
               type: string
@@ -8854,7 +8863,7 @@ components:
                 $ref: "#/components/schemas/DMOFilterConfigInputRepresentation"
             segmentApiName:
               description: |
-                Developer name of the segment. Either marketSegmentId or segmentApiName must be present.
+                Developer name of the segment. Either marketSegmentId or segmentApiName must be present. Exclude this property for `ApiTriggered` activation types.
 
                 **Available Version:** 60.0
               type: string
@@ -8870,6 +8879,12 @@ components:
 
                 **Available Version:** 60.0
               type: boolean
+            sourceDmoName:
+              description: |
+                Developer name of the source DMO. Required for `ApiTriggered` activation types. Exclude this property for `Segment` activation types.
+
+                **Available Version:** 66.0
+              type: string
             staticDataConfig:
               description: |
                 Configuration of static data, which adds metadata or campaign details in the output. For example, `campaignId` or `campaignName`.
@@ -27004,6 +27019,17 @@ components:
                 **Available Version:** 60.0
               allOf:
                 - $ref: "#/components/schemas/ActivationTargetSubjectRepresentation"
+            activationType:
+              description: |
+                Type of activation. 
+
+                **Filter Group:** Small
+
+                **Available Version:** 66.0
+              type: string
+              enum:
+                - ApiTriggered
+                - Segment
             attributeLimitingExpressionConfig:
               description: |
                 Limiting expression configuration for the activation.
@@ -27193,7 +27219,7 @@ components:
               type: integer
             marketSegmentId:
               description: |
-                Segment ID of the activation.
+                Segment ID of the activation. Returned for `Segment` type activations.
 
                 **Filter Group:** Small
 
@@ -27238,15 +27264,15 @@ components:
                 - $ref: "#/components/schemas/DmoFiltersConfigRepresentation"
             segmentApiName:
               description: |
-                Segment API name.
+                Segment API name. Returned for `Segment` type activations.
 
                 **Filter Group:** Small
 
                 **Available Version:** 60.0
               type: string
             segmentId:
               description: |
-                Segment ID of the activation.
+                Segment ID of the activation. Returned for `Segment` type activations.
 
                 **Filter Group:** Small
 
@@ -27268,6 +27294,14 @@ components:
 
                 **Available Version:** 60.0
               type: boolean
+            sourceDmoName:
+              description: |
+                Developer name of the source DMO.
+
+                **Filter Group:** Small
+
+                **Available Version:** 66.0
+              type: string
             staticDataConfig:
               description: |
                 Static data configuration for the activation.

src/resources/calculated-insights.ts

@@ -1 +1,43 @@
-export { CalculatedInsightsServiceBase as CalculatedInsightsService } from "../generated/services/calculated-insights.base.js";
+import { CalculatedInsightsServiceBase } from "../generated/services/calculated-insights.base.js";
+import type { RequestOptions } from "../core/types.js";
+import type {
+  CdpCalculatedInsightInputRepresentation,
+  CdpCalculatedInsightRepresentation,
+} from "../schemas.js";
+
+export class CalculatedInsightsService extends CalculatedInsightsServiceBase {
+  /**
+   * POST /ssot/calculated-insights — Create calculated insight.
+   *
+   * Server-side timing: this endpoint runs SQL validation, schedule
+   * registration, and dependency-graph updates synchronously, and
+   * commonly takes 30–60 seconds for non-trivial expressions. The
+   * SDK's default 30s HTTP timeout aborts before the response arrives;
+   * pass `{ timeout: 120_000 }` (or longer) via `options` for any CI
+   * whose `expression` references multiple DMOs or large fact tables.
+   */
+  override async create(
+    body: CdpCalculatedInsightInputRepresentation,
+    options?: RequestOptions,
+  ): Promise<CdpCalculatedInsightRepresentation> {
+    return super.create(body, options);
+  }
+
+  /**
+   * DELETE /ssot/calculated-insights/{apiName} — Delete calculated insight.
+   *
+   * Asynchronous teardown: the response is 204 immediately, but the
+   * record sits at `status = "DELETING"` for several minutes before
+   * becoming truly gone. During that window:
+   *   - GET still returns the CI (with the DELETING status)
+   *   - A re-create attempt with the same apiName 400s with
+   *     DUPLICATES_DETECTED until teardown completes
+   *
+   * Callers performing a delete-then-recreate flow should poll the
+   * CI's `status` until either (a) GET returns 404 or (b) the status
+   * is no longer `DELETING`, before re-creating with the same apiName.
+   */
+  override async delete(apiName: string, options?: RequestOptions): Promise<void> {
+    return super.delete(apiName, options);
+  }
+}