Add runtime overrides and JSDoc for discovered API quirks

Discovered via live-org validation from a downstream consumer. The
spec is technically correct but silent about server-side constraints
and edge cases; these overrides/JSDoc capture what the API actually
requires.

Behavior changes:
- data-model-objects.listMappings: soft-lands the "Object Source Target
  Map not found" 404 as an empty collection. Unrelated 404s and other
  errors still throw.
- data-graphs: adds list() / listAll() convenience wrappers over
  getMetadata (the Connect API has no dedicated list endpoint).

Documentation / JSDoc:
- connections.list: documents connectorType casing caveats (CamelCase
  vs UPPERCASE varies by connector family).
- connections.listSchema: documents that only a subset of connector
  types is supported; AwsS3/Databricks/SalesforceDotCom reject with
  ILLEGAL_QUERY_PARAMETER_VALUE.
- connectors: class-level JSDoc explains the casing variance and the
  connectorInfoList collection key.
- data-kits.list / listAvailableComponents: notes known tenant-side
  timeouts and 500s with Metadata API fallback recommendation.
- data-model-objects: class-level note on the singular
  dataModelObject response key.
- identity-resolutions: class-level JSDoc clarifying that get/delete/
  patch/runNow require the id, not developerName.

Tests: 3 new cases locking listMappings 404 soft-landing behavior, 3
new cases for DataGraphs list()/listAll(); fixed pre-existing
createMappings and getData call shapes.

215 tests passing (+6), typecheck clean, build clean.

Author: javrrr

README.md

@@ -258,7 +258,7 @@ if (queryId) {
 | Data Action Targets | `client.dataActionTargets` | list, listAll, get, create, delete, getSigningKey, createSigningKey, resetSigningKey |
 | Data Actions | `client.dataActions` | list, listAll, create |
 | Data Clean Room | `client.dataCleanRoom` | listCollaborations, listAllCollaborations, createCollaborations, acceptInvitation, rejectInvitation, run, listCollaborationsJobs, listAllCollaborationsJobs, listProviders, listAllProviders, createProviders, getProviders, listProvidersTemplates, listAllProvidersTemplates, listSpecifications, listAllSpecifications, createSpecifications, listTemplates, listAllTemplates |
-| Data Graphs | `client.dataGraphs` | get, create, delete, refresh, getData, getDataByGet, getMetadata |
+| Data Graphs | `client.dataGraphs` | list, listAll, get, create, delete, refresh, getData, getDataByGet, getMetadata |
 | Data Kits | `client.dataKits` | list, create, delete, patch, createByPost, listDependencies, getDeploymentStatus, createUndeploy, listAvailableComponents, getDataKitManifest |
 | Data Lake Objects | `client.dataLakeObjects` | list, listAll, get, create, delete, patch |
 | Data Model Objects | `client.dataModelObjects` | list, listAll, get, create, delete, patch, listRelationships, listAllRelationships, createRelationships, deleteRelationships, listMappings, listAllMappings, getMappings, createMappings, deleteMappings, deleteMappingsFieldMappings, patchMappingsFieldMappings |

src/resources/connections.ts

@@ -1,14 +1,38 @@
 import { ConnectionsServiceBase } from "../generated/services/connections.base.js";
-import type { RequestOptions } from "../core/types.js";
+import type { ConnectionsListParams } from "../generated/services/connections.base.js";
+import type { PaginationParams, RequestOptions } from "../core/types.js";
 import type {
+  ConnectionCollectionRepresentation,
   ConnectionCreateInput,
   ConnectionInputRepresentation,
   ConnectionRepresentation,
+  ConnectionSchemaCollectionRepresentation,
   ConnectionUpdateInput,
   ConnectionPatchInputRepresentation,
 } from "../schemas.js";
 
 export class ConnectionsService extends ConnectionsServiceBase {
+  /**
+   * GET /ssot/connections — Get connections.
+   *
+   * The `connectorType` query parameter is required and must match exactly
+   * one of the connector `name` values returned by `connectors.list`. The
+   * casing is backend-defined per connector family: some types accept
+   * CamelCase (`IngestApi`, `SalesforceDotCom`, `AwsS3`, `AzureBlob`,
+   * `Databricks`), others only accept UPPERCASE (`SNOWFLAKE`, `BIGQUERY`,
+   * `GCS`, `SFTP`). Passing a mismatched token returns
+   * `400 ILLEGAL_QUERY_PARAMETER_VALUE` with a message like
+   * `ConnectorType [Snowflake] is not supported`. If you do not know the
+   * exact token for a target connector, enumerate it via `connectors.list`
+   * first.
+   */
+  override async list(
+    params: PaginationParams & ConnectionsListParams,
+    options?: RequestOptions,
+  ): Promise<ConnectionCollectionRepresentation> {
+    return super.list(params, options);
+  }
+
   /** Override create with discriminated union input type. */
   override async create(body: ConnectionCreateInput | ConnectionInputRepresentation, options?: RequestOptions): Promise<ConnectionRepresentation> {
     return this.httpClient.post(this.basePath, body, options);
@@ -23,4 +47,25 @@ export class ConnectionsService extends ConnectionsServiceBase {
   async update(connectionId: string, body: ConnectionUpdateInput | ConnectionPatchInputRepresentation, options?: RequestOptions): Promise<ConnectionRepresentation> {
     return this.httpClient.patch(`${this.basePath}/${encodeURIComponent(connectionId)}`, body, options);
   }
+
+  /**
+   * GET /ssot/connections/{connectionId}/schema — Get connection schema.
+   *
+   * Only a subset of connector types is supported by this endpoint. In
+   * practice the API accepts IngestApi connections and rejects AwsS3,
+   * Databricks, and SalesforceDotCom connections with
+   * `400 ILLEGAL_QUERY_PARAMETER_VALUE`
+   * (`No enum constant ConnectionSchemaTypeEnum.<type>`).
+   *
+   * The SDK surface exposes the method uniformly; callers that cannot predict
+   * the connector type of a given connection ID should wrap this call and
+   * fall back to `getEndpoints` or parse the schema from the connection
+   * payload returned by `get(connectionId)`.
+   */
+  override async listSchema(
+    connectionId: string,
+    options?: RequestOptions,
+  ): Promise<ConnectionSchemaCollectionRepresentation> {
+    return super.listSchema(connectionId, options);
+  }
 }

src/resources/connectors.ts

@@ -1 +1,26 @@
-export { ConnectorsServiceBase as ConnectorsService } from "../generated/services/connectors.base.js";
+import { ConnectorsServiceBase } from "../generated/services/connectors.base.js";
+import type { PaginationParams, RequestOptions } from "../core/types.js";
+import type { ConnectorsListParams } from "../generated/services/connectors.base.js";
+import type { ConnectorInfoCollectionRepresentation } from "../schemas.js";
+
+/**
+ * Connector catalog — the list of connector types available in the org.
+ *
+ * Use this to discover the exact `name` value to pass as `connectorType` to
+ * `connections.list`. The accepted token is the catalog `name`, which can be
+ * either CamelCase (`IngestApi`, `SalesforceDotCom`, `AwsS3`, `AzureBlob`,
+ * `Databricks`) or UPPERCASE (`SNOWFLAKE`, `BIGQUERY`, `GCS`, `SFTP`),
+ * depending on the connector family — there is no blanket casing rule.
+ * Treat the connector type string as an API-supplied enum and probe via
+ * this catalog when in doubt.
+ *
+ * Collection response key: `connectorInfoList`.
+ */
+export class ConnectorsService extends ConnectorsServiceBase {
+  override async list(
+    params?: PaginationParams & ConnectorsListParams,
+    options?: RequestOptions,
+  ): Promise<ConnectorInfoCollectionRepresentation> {
+    return super.list(params, options);
+  }
+}

src/resources/data-graphs.ts

@@ -1 +1,34 @@
-export { DataGraphsServiceBase as DataGraphsService } from "../generated/services/data-graphs.base.js";
+import { DataGraphsServiceBase } from "../generated/services/data-graphs.base.js";
+import type { DataGraphsGetMetadataParams } from "../generated/services/data-graphs.base.js";
+import type { RequestOptions } from "../core/types.js";
+import type { CdpQueryDataGraphMetadataRepresentation } from "../schemas.js";
+
+export class DataGraphsService extends DataGraphsServiceBase {
+  /**
+   * Convenience wrapper over `getMetadata` — the Data 360 Connect API does not
+   * expose a dedicated `GET /ssot/data-graphs` endpoint, so enumeration goes
+   * through `GET /ssot/data-graphs/metadata` (`getMetadata`). This helper
+   * unwraps `dataGraphMetadata` and returns the array of descriptors
+   * directly, mirroring the shape other `.list()` methods return.
+   *
+   * Real-time and standard data graphs are returned in the same list and are
+   * distinguished by fields on each descriptor, not by endpoint.
+   */
+  async list(
+    params?: DataGraphsGetMetadataParams,
+    options?: RequestOptions,
+  ): Promise<CdpQueryDataGraphMetadataRepresentation[]> {
+    const res = await this.getMetadata(params, options);
+    return res.dataGraphMetadata ?? [];
+  }
+
+  /** Async iterator over `list()` — emitted for parity with other services. */
+  async *listAll(
+    params?: DataGraphsGetMetadataParams,
+    options?: RequestOptions,
+  ): AsyncGenerator<CdpQueryDataGraphMetadataRepresentation, void, undefined> {
+    for (const item of await this.list(params, options)) {
+      yield item;
+    }
+  }
+}

src/resources/data-kits.ts

@@ -1 +1,41 @@
-export { DataKitsServiceBase as DataKitsService } from "../generated/services/data-kits.base.js";
+import { DataKitsServiceBase } from "../generated/services/data-kits.base.js";
+import type { DataKitsListParams, DataKitsListAvailableComponentsParams } from "../generated/services/data-kits.base.js";
+import type { PaginationParams, RequestOptions } from "../core/types.js";
+import type {
+  DataKitComponentCollectionRepresentation,
+  DataKitOutputRepresentation,
+} from "../schemas.js";
+
+export class DataKitsService extends DataKitsServiceBase {
+  /**
+   * GET /ssot/data-kits — Get data kits.
+   *
+   * Known tenant-side reliability issue: this endpoint can take > 60s to
+   * respond or time out entirely on orgs with many installed data kits. If
+   * you hit a timeout, inventorying data kits via the Metadata API
+   * (`DataPackageKitDefinition` and `DataKitObjectTemplate` types) is a more
+   * reliable alternative. The Connect API remains the correct surface for
+   * `deploy` / `undeploy` actions.
+   */
+  override async list(
+    params?: DataKitsListParams,
+    options?: RequestOptions,
+  ): Promise<DataKitOutputRepresentation> {
+    return super.list(params, options);
+  }
+
+  /**
+   * GET /ssot/data-kits/available-components — Get data kit available components.
+   *
+   * Known tenant-side reliability issue: this endpoint has been observed
+   * returning `500 Server Error` on orgs with large data kit inventories.
+   * If that happens, fall back to reading `DataKitObjectTemplate` metadata
+   * via the sf CLI Metadata API.
+   */
+  override async listAvailableComponents(
+    params?: PaginationParams & DataKitsListAvailableComponentsParams,
+    options?: RequestOptions,
+  ): Promise<DataKitComponentCollectionRepresentation> {
+    return super.listAvailableComponents(params, options);
+  }
+}

src/resources/data-model-objects.ts

@@ -1 +1,65 @@
-export { DataModelObjectsServiceBase as DataModelObjectsService } from "../generated/services/data-model-objects.base.js";
+import { DataModelObjectsServiceBase } from "../generated/services/data-model-objects.base.js";
+import type { DataModelObjectsListMappingsParams } from "../generated/services/data-model-objects.base.js";
+import { NotFoundError } from "../core/errors.js";
+import type { PaginationParams, RequestOptions } from "../core/types.js";
+import type {
+  CdpObjectSourceTargetMapCollectionRepresentation,
+  DataModelObjectCollectionRepresentation,
+} from "../schemas.js";
+
+/**
+ * DMO response-shape note: `list()` returns a body whose array is under the
+ * **singular** key `dataModelObject` (not plural, unlike every other `list`
+ * method in the SDK). Destructure accordingly:
+ *
+ *   const { dataModelObject: items } = await client.dataModelObjects.list();
+ *
+ * This is a spec oddity that the generated types preserve; the override
+ * below intentionally does not reshape it so raw responses remain diffable
+ * against captured fixtures.
+ */
+export class DataModelObjectsService extends DataModelObjectsServiceBase {
+  override async list(
+    params?: PaginationParams,
+    options?: RequestOptions,
+  ): Promise<DataModelObjectCollectionRepresentation> {
+    return super.list(params, options);
+  }
+
+  /**
+   * GET /ssot/data-model-object-mappings — Get data model object mappings.
+   *
+   * The API returns 404 `NOT_FOUND` (`Object Source Target Map not found for
+   * the given Target Object Dev Name`) when the DMO exists but has no
+   * mappings — notably for any `ssot__`-prefixed or UI-graph-generated DMO.
+   * This override catches that specific 404 and returns an empty collection
+   * so callers can iterate without a try/catch around every call.
+   *
+   * Non-404 errors (including 404s for a DMO that doesn't exist at all) are
+   * not suppressed — the body's error code disambiguates them upstream.
+   */
+  override async listMappings(
+    params: DataModelObjectsListMappingsParams,
+    options?: RequestOptions,
+  ): Promise<CdpObjectSourceTargetMapCollectionRepresentation> {
+    try {
+      return await super.listMappings(params, options);
+    } catch (e) {
+      if (e instanceof NotFoundError && isNoMappingsError(e)) {
+        return { objectSourceTargetMaps: [] } as CdpObjectSourceTargetMapCollectionRepresentation;
+      }
+      throw e;
+    }
+  }
+}
+
+function isNoMappingsError(err: NotFoundError): boolean {
+  const body = err.body as unknown;
+  if (!Array.isArray(body)) return false;
+  return body.some(
+    (e) =>
+      typeof e === "object" &&
+      e !== null &&
+      (e as { message?: string }).message?.startsWith("Object Source Target Map not found"),
+  );
+}

src/resources/identity-resolutions.ts

@@ -1 +1,36 @@
-export { IdentityResolutionsServiceBase as IdentityResolutionsService } from "../generated/services/identity-resolutions.base.js";
+import { IdentityResolutionsServiceBase } from "../generated/services/identity-resolutions.base.js";
+import type { RequestOptions } from "../core/types.js";
+import type {
+  CdpIdentityResolutionConfigPatchInput,
+  CdpIdentityResolutionOutputRepresentation,
+} from "../schemas.js";
+
+/**
+ * Identity resolution operations.
+ *
+ * Path parameter semantics (worth calling out because the SDK parameter name
+ * implies either option works): `get`, `delete`, `patch`, and `runNow` all
+ * require the identity resolution's **id** (e.g. `1irKa000000KzoZIAS`), not
+ * its `developerName`. The id is what appears in the list response. If you
+ * only have a developer name, resolve it via `list()` first.
+ */
+export class IdentityResolutionsService extends IdentityResolutionsServiceBase {
+  override async get(
+    identityResolution: string,
+    options?: RequestOptions,
+  ): Promise<CdpIdentityResolutionOutputRepresentation> {
+    return super.get(identityResolution, options);
+  }
+
+  override async delete(identityResolution: string, options?: RequestOptions): Promise<void> {
+    return super.delete(identityResolution, options);
+  }
+
+  override async patch(
+    identityResolution: string,
+    body: CdpIdentityResolutionConfigPatchInput,
+    options?: RequestOptions,
+  ): Promise<CdpIdentityResolutionOutputRepresentation> {
+    return super.patch(identityResolution, body, options);
+  }
+}

tests/resources/data-graphs.test.ts

@@ -20,6 +20,43 @@ describe("DataGraphsService", () => {
     expect(httpClient.get).toHaveBeenCalled();
   });
 
+  it("list() unwraps dataGraphMetadata from getMetadata response", async () => {
+    const items = [{ developerName: "A" }, { developerName: "B" }];
+    const httpClient = {
+      get: vi.fn(async () => ({ dataGraphMetadata: items })),
+    } as unknown as HttpClient;
+    const service = new DataGraphsService(httpClient);
+
+    const res = await service.list();
+    expect(res).toEqual(items);
+    expect(httpClient.get).toHaveBeenCalledWith(
+      "/ssot/data-graphs/metadata",
+      expect.objectContaining({ query: undefined }),
+    );
+  });
+
+  it("list() returns [] when dataGraphMetadata is missing", async () => {
+    const httpClient = {
+      get: vi.fn(async () => ({})),
+    } as unknown as HttpClient;
+    const service = new DataGraphsService(httpClient);
+
+    const res = await service.list();
+    expect(res).toEqual([]);
+  });
+
+  it("listAll() yields each descriptor", async () => {
+    const items = [{ developerName: "A" }, { developerName: "B" }];
+    const httpClient = {
+      get: vi.fn(async () => ({ dataGraphMetadata: items })),
+    } as unknown as HttpClient;
+    const service = new DataGraphsService(httpClient);
+
+    const collected = [];
+    for await (const item of service.listAll()) collected.push(item);
+    expect(collected).toEqual(items);
+  });
+
   it("get()", async () => {
     const httpClient = createMockHttpClient();
     const service = new DataGraphsService(httpClient);
@@ -42,7 +79,7 @@ describe("DataGraphsService", () => {
     const httpClient = createMockHttpClient();
     const service = new DataGraphsService(httpClient);
 
-    await service.getData("test-entityName", { batchSize: 10 });
+    await service.getData("test-entityName", { lookupKeys: "Id=abc" });
 
     expect(httpClient.get).toHaveBeenCalled();
   });