catalyst-relay 0.6.3 → 0.6.5

package/dist/index.d.mts

@@ -598,6 +598,66 @@ interface SearchOptions {
  */
 type ClassIncludeType = 'definitions' | 'implementations' | 'macros' | 'testclasses';
 
+/**
+ * API Release types — shared across the apirelease module
+ *
+ * Models the C1 release contract of a CDS DDL source (DDLS). SAP exposes a
+ * generic API release framework (contracts C0–C4); this module is scoped to
+ * the C1 (customer / SAP Cloud Platform) contract on CDS queries.
+ */
+/**
+ * Release status of an API contract.
+ *
+ * These are the states SAP reports for the C1 contract on a CDS DDL source.
+ */
+type ApiReleaseStatus = 'NOT_RELEASED' | 'RELEASED' | 'DEPRECATED' | 'NOT_TO_BE_RELEASED' | 'NOT_TO_BE_RELEASED_STABLE';
+/**
+ * A message returned by the contract validation run (pre-flight check).
+ *
+ * Warnings (e.g. "referenced data element is not released") are informational
+ * and do not block the operation; errors do.
+ */
+interface ApiReleaseValidationMessage {
+    severity: 'error' | 'warning' | 'info';
+    text: string;
+    /** SAP message class (e.g. ARS_DEP_CHECKS), if present. */
+    msgid?: string;
+    /** SAP message number, if present. */
+    msgno?: string;
+}
+/**
+ * Current C1 release state of a CDS DDL source.
+ */
+interface ApiReleaseState {
+    /** Object name (e.g. ZSNAP_F04S_Q01). */
+    name: string;
+    /** Releasable object ADT URI (e.g. /sap/bc/adt/ddic/ddl/sources/zsnap_f04s_q01). */
+    uri: string;
+    /** Current C1 contract status. */
+    status: ApiReleaseStatus;
+    /** Human-readable status description (e.g. "Released"). */
+    statusDescription: string;
+    /** Convenience flag: true when status is RELEASED. */
+    released: boolean;
+    /** States the C1 contract can transition to from the current status. */
+    allowedTransitions: ApiReleaseStatus[];
+    /** User who last changed the C1 contract, if any. */
+    changedBy?: string;
+    /** Timestamp the C1 contract was last changed, if any. */
+    changedAt?: string;
+}
+/**
+ * Result of a release / unrelease operation.
+ */
+interface ApiReleaseResult {
+    /** Object name (e.g. ZSNAP_F04S_Q01). */
+    name: string;
+    /** Resulting C1 contract status after the operation. */
+    status: ApiReleaseStatus;
+    /** Non-blocking validation messages surfaced during the operation. */
+    messages: ApiReleaseValidationMessage[];
+}
+
 /**
  * Create Transport — create a new transport request.
  *
@@ -775,6 +835,9 @@ interface ADTClient {
     gitDiff(objects: ObjectContent[]): AsyncResult<DiffResult[]>;
     createServiceBinding(options: CreateServiceBindingOptions): AsyncResult<ServiceBindingResult>;
     deleteServiceBinding(bindingName: string, transport?: string): AsyncResult<void>;
+    getApiReleaseState(objectName: string): AsyncResult<ApiReleaseState>;
+    releaseApi(objectName: string, transport?: string): AsyncResult<ApiReleaseResult>;
+    unreleaseApi(objectName: string, transport?: string): AsyncResult<ApiReleaseResult>;
     getObjectConfig(): ObjectConfig[];
 }
 
@@ -800,4 +863,4 @@ declare function activateLogging(): void;
  */
 declare function deactivateLogging(): void;
 
-export { type ADTClient, type ActivationMessage, type ActivationReference, type ActivationResult, type Aggregation, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type BasicFilter, BehaviorImplementationType, type BetweenFilter, type CheckResult, type ClassIncludeType, type ClientConfig, type ColumnInfo, type CreateServiceBindingOptions, type DataFrame, type DataPreviewQuery, type DeleteResult, type Dependency, type DiffHunk, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type ExportableSessionState, type ExternalReference, ExternalReferencesError, type FolderNode, type GetPackagesOptions, type InactiveEntry, type InactiveObject, type InactiveRef, type InactiveTransport, type ListFilter, type ModifiedDiffHunk, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectNode, type ObjectRef, type ObjectWithContent, type Package, type PackageNode, type Parameter, type PreviewSQL, type QueryFilter, type Result, type SamlAuthConfig, type SearchOptions, type SearchResult, type ServiceBindingResult, type ServiceBindingType, type ServiceBindingVersion, type Session, type SimpleDiffHunk, type Sorting, type SsoAuthConfig, type SuccessResponse, type TaskContents, type Transport, type TransportConfig, type TransportObject, type TransportType, type TreeQuery, type TreeResponse, type UpsertResult, activateLogging, buildSQLQuery, createClient, deactivateLogging, err, ok };
+export { type ADTClient, type ActivationMessage, type ActivationReference, type ActivationResult, type Aggregation, type ApiReleaseResult, type ApiReleaseState, type ApiReleaseStatus, type ApiReleaseValidationMessage, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type BasicFilter, BehaviorImplementationType, type BetweenFilter, type CheckResult, type ClassIncludeType, type ClientConfig, type ColumnInfo, type CreateServiceBindingOptions, type DataFrame, type DataPreviewQuery, type DeleteResult, type Dependency, type DiffHunk, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type ExportableSessionState, type ExternalReference, ExternalReferencesError, type FolderNode, type GetPackagesOptions, type InactiveEntry, type InactiveObject, type InactiveRef, type InactiveTransport, type ListFilter, type ModifiedDiffHunk, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectNode, type ObjectRef, type ObjectWithContent, type Package, type PackageNode, type Parameter, type PreviewSQL, type QueryFilter, type Result, type SamlAuthConfig, type SearchOptions, type SearchResult, type ServiceBindingResult, type ServiceBindingType, type ServiceBindingVersion, type Session, type SimpleDiffHunk, type Sorting, type SsoAuthConfig, type SuccessResponse, type TaskContents, type Transport, type TransportConfig, type TransportObject, type TransportType, type TreeQuery, type TreeResponse, type UpsertResult, activateLogging, buildSQLQuery, createClient, deactivateLogging, err, ok };

package/dist/index.d.ts

@@ -598,6 +598,66 @@ interface SearchOptions {
  */
 type ClassIncludeType = 'definitions' | 'implementations' | 'macros' | 'testclasses';
 
+/**
+ * API Release types — shared across the apirelease module
+ *
+ * Models the C1 release contract of a CDS DDL source (DDLS). SAP exposes a
+ * generic API release framework (contracts C0–C4); this module is scoped to
+ * the C1 (customer / SAP Cloud Platform) contract on CDS queries.
+ */
+/**
+ * Release status of an API contract.
+ *
+ * These are the states SAP reports for the C1 contract on a CDS DDL source.
+ */
+type ApiReleaseStatus = 'NOT_RELEASED' | 'RELEASED' | 'DEPRECATED' | 'NOT_TO_BE_RELEASED' | 'NOT_TO_BE_RELEASED_STABLE';
+/**
+ * A message returned by the contract validation run (pre-flight check).
+ *
+ * Warnings (e.g. "referenced data element is not released") are informational
+ * and do not block the operation; errors do.
+ */
+interface ApiReleaseValidationMessage {
+    severity: 'error' | 'warning' | 'info';
+    text: string;
+    /** SAP message class (e.g. ARS_DEP_CHECKS), if present. */
+    msgid?: string;
+    /** SAP message number, if present. */
+    msgno?: string;
+}
+/**
+ * Current C1 release state of a CDS DDL source.
+ */
+interface ApiReleaseState {
+    /** Object name (e.g. ZSNAP_F04S_Q01). */
+    name: string;
+    /** Releasable object ADT URI (e.g. /sap/bc/adt/ddic/ddl/sources/zsnap_f04s_q01). */
+    uri: string;
+    /** Current C1 contract status. */
+    status: ApiReleaseStatus;
+    /** Human-readable status description (e.g. "Released"). */
+    statusDescription: string;
+    /** Convenience flag: true when status is RELEASED. */
+    released: boolean;
+    /** States the C1 contract can transition to from the current status. */
+    allowedTransitions: ApiReleaseStatus[];
+    /** User who last changed the C1 contract, if any. */
+    changedBy?: string;
+    /** Timestamp the C1 contract was last changed, if any. */
+    changedAt?: string;
+}
+/**
+ * Result of a release / unrelease operation.
+ */
+interface ApiReleaseResult {
+    /** Object name (e.g. ZSNAP_F04S_Q01). */
+    name: string;
+    /** Resulting C1 contract status after the operation. */
+    status: ApiReleaseStatus;
+    /** Non-blocking validation messages surfaced during the operation. */
+    messages: ApiReleaseValidationMessage[];
+}
+
 /**
  * Create Transport — create a new transport request.
  *
@@ -775,6 +835,9 @@ interface ADTClient {
     gitDiff(objects: ObjectContent[]): AsyncResult<DiffResult[]>;
     createServiceBinding(options: CreateServiceBindingOptions): AsyncResult<ServiceBindingResult>;
     deleteServiceBinding(bindingName: string, transport?: string): AsyncResult<void>;
+    getApiReleaseState(objectName: string): AsyncResult<ApiReleaseState>;
+    releaseApi(objectName: string, transport?: string): AsyncResult<ApiReleaseResult>;
+    unreleaseApi(objectName: string, transport?: string): AsyncResult<ApiReleaseResult>;
     getObjectConfig(): ObjectConfig[];
 }
 
@@ -800,4 +863,4 @@ declare function activateLogging(): void;
  */
 declare function deactivateLogging(): void;
 
-export { type ADTClient, type ActivationMessage, type ActivationReference, type ActivationResult, type Aggregation, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type BasicFilter, BehaviorImplementationType, type BetweenFilter, type CheckResult, type ClassIncludeType, type ClientConfig, type ColumnInfo, type CreateServiceBindingOptions, type DataFrame, type DataPreviewQuery, type DeleteResult, type Dependency, type DiffHunk, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type ExportableSessionState, type ExternalReference, ExternalReferencesError, type FolderNode, type GetPackagesOptions, type InactiveEntry, type InactiveObject, type InactiveRef, type InactiveTransport, type ListFilter, type ModifiedDiffHunk, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectNode, type ObjectRef, type ObjectWithContent, type Package, type PackageNode, type Parameter, type PreviewSQL, type QueryFilter, type Result, type SamlAuthConfig, type SearchOptions, type SearchResult, type ServiceBindingResult, type ServiceBindingType, type ServiceBindingVersion, type Session, type SimpleDiffHunk, type Sorting, type SsoAuthConfig, type SuccessResponse, type TaskContents, type Transport, type TransportConfig, type TransportObject, type TransportType, type TreeQuery, type TreeResponse, type UpsertResult, activateLogging, buildSQLQuery, createClient, deactivateLogging, err, ok };
+export { type ADTClient, type ActivationMessage, type ActivationReference, type ActivationResult, type Aggregation, type ApiReleaseResult, type ApiReleaseState, type ApiReleaseStatus, type ApiReleaseValidationMessage, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type BasicFilter, BehaviorImplementationType, type BetweenFilter, type CheckResult, type ClassIncludeType, type ClientConfig, type ColumnInfo, type CreateServiceBindingOptions, type DataFrame, type DataPreviewQuery, type DeleteResult, type Dependency, type DiffHunk, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type ExportableSessionState, type ExternalReference, ExternalReferencesError, type FolderNode, type GetPackagesOptions, type InactiveEntry, type InactiveObject, type InactiveRef, type InactiveTransport, type ListFilter, type ModifiedDiffHunk, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectNode, type ObjectRef, type ObjectWithContent, type Package, type PackageNode, type Parameter, type PreviewSQL, type QueryFilter, type Result, type SamlAuthConfig, type SearchOptions, type SearchResult, type ServiceBindingResult, type ServiceBindingType, type ServiceBindingVersion, type Session, type SimpleDiffHunk, type Sorting, type SsoAuthConfig, type SuccessResponse, type TaskContents, type Transport, type TransportConfig, type TransportObject, type TransportType, type TreeQuery, type TreeResponse, type UpsertResult, activateLogging, buildSQLQuery, createClient, deactivateLogging, err, ok };

package/dist/index.js

@@ -1934,6 +1934,7 @@ async function updateClassInclude(client, className, includeType, source, lockHa
 // src/core/adt/craud/activation.ts
 var MAX_POLL_ATTEMPTS = 30;
 var POLL_RETRY_DELAY_MS = 1e3;
+var LONG_POLL_TIMEOUT_MS = 36e5;
 var RUN_ID_REGEX = /\/activation\/runs\/([^?/]+)/;
 var BACKGROUND_RUN_MEDIA_TYPE = "application/vnd.sap.adt.backgroundrun.v1+xml";
 async function activateObjects(client, objects) {
@@ -1996,7 +1997,8 @@ async function activateByReferences(client, references) {
       method: "GET",
       path: `/sap/bc/adt/activation/runs/${runId}`,
       params: { "withLongPolling": "true" },
-      headers: { "Accept": BACKGROUND_RUN_MEDIA_TYPE }
+      headers: { "Accept": BACKGROUND_RUN_MEDIA_TYPE },
+      timeout: LONG_POLL_TIMEOUT_MS
     });
     if (pollErr) return err(pollErr);
     debug(`Activation poll attempt ${pollAttempt} status: ${pollRes.status}`);
@@ -2086,6 +2088,192 @@ function extractActivationErrors(objects, xml) {
   return ok(results);
 }
 
+// src/core/adt/craud/apirelease/helpers.ts
+var DDLS_ENDPOINT = "ddic/ddl/sources";
+var CONTRACT_PATH = "c1";
+var CONTRACT_ELEMENT = "ars:c1Release";
+var APIRELEASE_MEDIA_TYPE = "application/vnd.sap.adt.apirelease.v10+xml";
+var APIRELEASE_VALIDATION_CONTENT_TYPE = "application/vnd.sap.adt.apireleasecontractvalidation+xml";
+var APIRELEASE_VALIDATION_ACCEPT = "application/vnd.sap.adt.apireleasecontractvalidation+xml, application/vnd.sap.adt.apireleasecontractvalidation.v2+xml";
+function buildReleasableUri(name) {
+  return `/sap/bc/adt/${DDLS_ENDPOINT}/${name.toLowerCase()}`;
+}
+function buildApiReleasePath(name) {
+  return `/sap/bc/adt/apireleases/${encodeURIComponent(buildReleasableUri(name))}`;
+}
+function buildContractPath(name) {
+  return `${buildApiReleasePath(name)}/${CONTRACT_PATH}`;
+}
+function buildValidationRunPath(name) {
+  return `${buildContractPath(name)}/validationrun`;
+}
+function buildC1ReleaseBody(status) {
+  return `<?xml version="1.0" encoding="UTF-8"?><ars:apiRelease xmlns:ars="http://www.sap.com/adt/ars">
+  <ars:c1Release ars:comment="" ars:contract="C1" ars:createAuthValues="false" ars:featureToggle="" ars:useInKeyUserApps="true" ars:useInSAPCloudPlatform="true">
+    <ars:status ars:state="${status}"/>
+    <ars:useConceptAsSuccessor>false</ars:useConceptAsSuccessor>
+    <ars:successors/>
+    <ars:successorConceptName/>
+  </ars:c1Release>
+  <ars:apiCatalogData ars:isAnyAssignmentPossible="false" ars:isAnyContractReleased="false">
+    <ars:ApiCatalogs/>
+  </ars:apiCatalogData>
+</ars:apiRelease>`;
+}
+function toStatus(state) {
+  return state;
+}
+function findContractElement(doc) {
+  const candidates = doc.getElementsByTagName(CONTRACT_ELEMENT);
+  for (let i = 0; i < candidates.length; i++) {
+    const el = candidates[i];
+    if (!el) continue;
+    if (el.getElementsByTagName("ars:status").length === 0) continue;
+    return el;
+  }
+  return null;
+}
+function parseReleaseState(xml, fallbackName) {
+  const [doc, parseErr] = safeParseXml(xml);
+  if (parseErr) return err(parseErr);
+  const contract = findContractElement(doc);
+  if (!contract) return err(new Error("apiRelease response missing C1 contract element"));
+  const statusEl = contract.getElementsByTagName("ars:status")[0];
+  const state = statusEl?.getAttribute("ars:state");
+  if (!state) return err(new Error("apiRelease response missing C1 status"));
+  const statusDescription = statusEl?.getAttribute("ars:stateDescription") ?? "";
+  const allowedTransitions = [];
+  const transitionsEl = contract.getElementsByTagName("ars:stateTransitions")[0];
+  if (transitionsEl) {
+    const transitionStatuses = transitionsEl.getElementsByTagName("ars:status");
+    for (let i = 0; i < transitionStatuses.length; i++) {
+      const transitionState = transitionStatuses[i]?.getAttribute("ars:state");
+      if (transitionState) allowedTransitions.push(toStatus(transitionState));
+    }
+  }
+  const releasable = doc.getElementsByTagName("ars:releasableObject")[0];
+  const name = releasable?.getAttribute("adtcore:name") ?? fallbackName;
+  const uri = releasable?.getAttribute("adtcore:uri") ?? buildReleasableUri(fallbackName);
+  const result = {
+    name,
+    uri,
+    status: toStatus(state),
+    statusDescription,
+    released: state === "RELEASED",
+    allowedTransitions
+  };
+  const changedBy = contract.getAttribute("adtcore:changedBy");
+  if (changedBy) result.changedBy = changedBy;
+  const changedAt = contract.getAttribute("adtcore:changedAt");
+  if (changedAt) result.changedAt = changedAt;
+  return ok(result);
+}
+function parseValidationMessages(xml) {
+  const [doc, parseErr] = safeParseXml(xml);
+  if (parseErr) return [];
+  const messages = [];
+  const elements = doc.getElementsByTagName("ars:validationMessage");
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    if (!el) continue;
+    const text = el.getAttribute("text");
+    if (!text) continue;
+    const message = {
+      severity: mapSeverity(el.getAttribute("type")),
+      text
+    };
+    const msgid = el.getAttribute("msgid");
+    if (msgid) message.msgid = msgid;
+    const msgno = el.getAttribute("msgno");
+    if (msgno) message.msgno = msgno;
+    messages.push(message);
+  }
+  return messages;
+}
+function collectErrors(messages) {
+  return messages.filter((m) => m.severity === "error");
+}
+function mapSeverity(type) {
+  if (type === "E" || type === "A" || type === "X") return "error";
+  if (type === "W") return "warning";
+  return "info";
+}
+
+// src/core/adt/craud/apirelease/getState.ts
+async function getApiReleaseState(client, objectName) {
+  const [response, requestErr] = await client.request({
+    method: "GET",
+    path: buildApiReleasePath(objectName),
+    headers: { "Accept": APIRELEASE_MEDIA_TYPE }
+  });
+  const [text, checkErr] = await checkResponse(
+    response,
+    requestErr,
+    `Failed to read API release state for ${objectName}`
+  );
+  if (checkErr) return err(checkErr);
+  const [state, parseErr] = parseReleaseState(text, objectName);
+  if (parseErr) return err(parseErr);
+  return ok(state);
+}
+
+// src/core/adt/craud/apirelease/release.ts
+async function releaseApi(client, objectName, transport) {
+  return setApiReleaseState(client, objectName, "RELEASED", transport);
+}
+async function unreleaseApi(client, objectName, transport) {
+  return setApiReleaseState(client, objectName, "NOT_RELEASED", transport);
+}
+async function setApiReleaseState(client, objectName, status, transport) {
+  const body = buildC1ReleaseBody(status);
+  const [validationRes, validationReqErr] = await client.request({
+    method: "POST",
+    path: buildValidationRunPath(objectName),
+    headers: {
+      "Content-Type": APIRELEASE_VALIDATION_CONTENT_TYPE,
+      "Accept": APIRELEASE_VALIDATION_ACCEPT
+    },
+    body
+  });
+  const [validationText, validationCheckErr] = await checkResponse(
+    validationRes,
+    validationReqErr,
+    `API release validation failed for ${objectName}`
+  );
+  if (validationCheckErr) return err(validationCheckErr);
+  const messages = parseValidationMessages(validationText);
+  const errors = collectErrors(messages);
+  if (errors.length > 0) {
+    const detail = errors.map((e) => e.text).join("; ");
+    return err(new Error(`API release validation failed for ${objectName}: ${detail}`));
+  }
+  const params = {};
+  if (transport) params["request"] = transport;
+  const [putRes, putReqErr] = await client.request({
+    method: "PUT",
+    path: buildContractPath(objectName),
+    params,
+    headers: {
+      "Content-Type": APIRELEASE_MEDIA_TYPE,
+      "Accept": APIRELEASE_MEDIA_TYPE
+    },
+    body
+  });
+  const [putText, putCheckErr] = await checkResponse(
+    putRes,
+    putReqErr,
+    `Failed to set API release state for ${objectName}`
+  );
+  if (putCheckErr) return err(putCheckErr);
+  const [state, parseErr] = parseReleaseState(putText, objectName);
+  if (parseErr) return err(parseErr);
+  return ok({
+    name: state.name,
+    status: state.status,
+    messages
+  });
+}
+
 // src/core/adt/craud/syntaxCheck.ts
 async function checkSyntax(client, objects) {
   if (objects.length === 0) {
@@ -3918,6 +4106,24 @@ async function deleteServiceBinding2(state, requestor, bindingName, transport) {
   return deleteServiceBinding(requestor, bindingName, transport);
 }
 
+// src/client/methods/apirelease/getApiReleaseState.ts
+async function getApiReleaseState2(state, requestor, objectName) {
+  if (!state.session) return err(new Error("Not logged in"));
+  return getApiReleaseState(requestor, objectName);
+}
+
+// src/client/methods/apirelease/releaseApi.ts
+async function releaseApi2(state, requestor, objectName, transport) {
+  if (!state.session) return err(new Error("Not logged in"));
+  return releaseApi(requestor, objectName, transport);
+}
+
+// src/client/methods/apirelease/unreleaseApi.ts
+async function unreleaseApi2(state, requestor, objectName, transport) {
+  if (!state.session) return err(new Error("Not logged in"));
+  return unreleaseApi(requestor, objectName, transport);
+}
+
 // src/client/methods/internal/cookies.ts
 function storeCookies(cookies, response) {
   const setCookieHeader = response.headers.get("set-cookie");
@@ -4308,6 +4514,16 @@ var ADTClientImpl = class {
   async deleteServiceBinding(bindingName, transport) {
     return deleteServiceBinding2(this.state, this.requestor, bindingName, transport);
   }
+  // --- API Release ---
+  async getApiReleaseState(objectName) {
+    return getApiReleaseState2(this.state, this.requestor, objectName);
+  }
+  async releaseApi(objectName, transport) {
+    return releaseApi2(this.state, this.requestor, objectName, transport);
+  }
+  async unreleaseApi(objectName, transport) {
+    return unreleaseApi2(this.state, this.requestor, objectName, transport);
+  }
   // --- Configuration ---
   getObjectConfig() {
     return getObjectConfig();