@devsym/subscription-portal-s2s-client 1.1.0

package/dist/index.cjs

@@ -0,0 +1,449 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PortalS2sClient: () => PortalS2sClient,
+  PortalS2sError: () => PortalS2sError,
+  S2S_API_VERSION: () => S2S_API_VERSION,
+  defaultTokenProvider: () => defaultTokenProvider
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var PortalS2sError = class extends Error {
+  status;
+  code;
+  correlationId;
+  details;
+  constructor(options) {
+    super(options.message);
+    this.name = "PortalS2sError";
+    this.status = options.status;
+    this.code = options.code;
+    this.correlationId = options.correlationId;
+    this.details = options.details;
+  }
+};
+
+// src/retry.ts
+var MAX_ATTEMPTS = 3;
+var MAX_RETRY_DELAY_MS = 3e4;
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var TransportRetryError = class extends Error {
+  cause;
+  constructor(cause) {
+    super("Portal request transport failed");
+    this.name = "TransportRetryError";
+    this.cause = cause;
+  }
+};
+function backoffDelay(attempt) {
+  const jitter = Math.floor(Math.random() * 100);
+  return 250 * 2 ** (attempt - 1) + jitter;
+}
+function retryAfterDelay(value) {
+  if (value === null) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    return Math.min(Number(trimmed) * 1e3, MAX_RETRY_DELAY_MS);
+  }
+  const timestamp = Date.parse(trimmed);
+  if (Number.isNaN(timestamp)) {
+    return void 0;
+  }
+  return Math.min(Math.max(0, timestamp - Date.now()), MAX_RETRY_DELAY_MS);
+}
+async function discardResponseBody(response) {
+  if (!response.body) {
+    return;
+  }
+  try {
+    await response.body.cancel();
+  } catch {
+    try {
+      await response.arrayBuffer();
+    } catch {
+    }
+  }
+}
+async function fetchWithRetry(operation, sleep) {
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    let response;
+    try {
+      response = await operation();
+    } catch (error) {
+      if (attempt === MAX_ATTEMPTS) {
+        throw new TransportRetryError(error);
+      }
+      await sleep(backoffDelay(attempt));
+      continue;
+    }
+    if (!RETRYABLE_STATUSES.has(response.status) || attempt === MAX_ATTEMPTS) {
+      return response;
+    }
+    await discardResponseBody(response);
+    await sleep(
+      Math.min(
+        retryAfterDelay(response.headers.get("retry-after")) ?? backoffDelay(attempt),
+        MAX_RETRY_DELAY_MS
+      )
+    );
+  }
+  throw new Error("Unreachable retry state");
+}
+
+// src/token-provider.ts
+var import_identity = require("@azure/identity");
+function defaultTokenProvider() {
+  return new import_identity.DefaultAzureCredential();
+}
+
+// src/client.ts
+var S2S_API_VERSION = "v1";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function isOptionalString(value) {
+  return value === void 0 || isString(value);
+}
+function isNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function isOneOf(value, choices) {
+  return isString(value) && choices.includes(value);
+}
+var providers = ["microsoft", "paddle", "trial", "manual"];
+var entitlementTypes = ["paid", "trial", "manual"];
+var subscriptionStatuses = [
+  "pending",
+  "active",
+  "suspended",
+  "canceled",
+  "expired",
+  "incomplete",
+  "unassigned"
+];
+function isSubscriptionStatusResponse(value) {
+  if (!isRecord(value) || !Array.isArray(value.subscriptions)) {
+    return false;
+  }
+  return isString(value.appId) && isString(value.microsoftTenantId) && isOptionalString(value.customerOrganizationId) && typeof value.hasActiveEntitlement === "boolean" && isNumber(value.aggregateEffectiveQuantity) && value.subscriptions.every((subscription) => isRecord(subscription) && isString(subscription.subscriptionId) && isOneOf(subscription.status, subscriptionStatuses) && isOneOf(subscription.entitlementType, entitlementTypes) && isOneOf(subscription.provider, providers) && (subscription.effectiveQuantity === void 0 || isNumber(subscription.effectiveQuantity)) && isOptionalString(subscription.lastSynchronizedOn));
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every(isString);
+}
+function isCapabilitiesResponse(value) {
+  return isRecord(value) && value.apiVersion === S2S_API_VERSION && isString(value.appId) && isOptionalString(value.portalVersion) && isStringArray(value.operations) && isStringArray(value.grantedRoles);
+}
+function isEntitlementsResponse(value) {
+  if (!isRecord(value) || !Array.isArray(value.items)) {
+    return false;
+  }
+  return isString(value.appId) && isString(value.microsoftTenantId) && isOptionalString(value.customerOrganizationId) && typeof value.hasActiveEntitlement === "boolean" && isNumber(value.aggregateEffectiveQuantity) && value.items.every((item) => isRecord(item) && isString(item.subscriptionId) && isOneOf(item.provider, providers) && isOneOf(item.entitlementType, entitlementTypes) && isString(item.status) && (item.effectiveQuantity === void 0 || isNumber(item.effectiveQuantity)) && isOptionalString(item.lastSynchronizedOn));
+}
+function isLinkageResponse(value) {
+  if (!isRecord(value) || !Array.isArray(value.claims)) {
+    return false;
+  }
+  const tenantLinkIsValid = value.tenantLink === void 0 || isRecord(value.tenantLink) && isOneOf(
+    value.tenantLink.linkSource,
+    ["activation", "claim", "manualAssignment", "trial"]
+  ) && isString(value.tenantLink.linkedOn) && typeof value.tenantLink.isActive === "boolean";
+  return isString(value.appId) && isString(value.microsoftTenantId) && isOptionalString(value.customerOrganizationId) && tenantLinkIsValid && value.claims.every((claim) => isRecord(claim) && isString(claim.subscriptionId) && isOneOf(claim.claimState, ["assigned", "unassigned", "released"]));
+}
+function isRedeemLicenseKeyResponse(value) {
+  return isRecord(value) && isOneOf(value.result, ["linked", "alreadyLinked"]) && isString(value.subscriptionId) && isString(value.customerOrganizationId) && isString(value.effectiveEntitledAppId) && isString(value.status) && isNumber(value.quantity) && isString(value.ownershipAcquisitionMode) && isString(value.correlationId);
+}
+function isReleaseClaimResponse(value) {
+  return isRecord(value) && value.result === "released" && isOptionalString(value.subscriptionId) && isString(value.correlationId);
+}
+function isStartTrialResponse(value) {
+  return isRecord(value) && isOneOf(value.result, ["started", "alreadyActive"]) && isString(value.subscriptionId) && isString(value.customerOrganizationId) && isOneOf(value.trialMode, ["timeBased", "seatLimited"]) && value.trialStatus === "active" && isString(value.trialStartOn) && isOptionalString(value.trialEndOn) && (value.trialSeatLimit === void 0 || isNumber(value.trialSeatLimit)) && (value.trialUsage === void 0 || isNumber(value.trialUsage)) && isString(value.correlationId);
+}
+function isSyncRequestResponse(value) {
+  return isRecord(value) && typeof value.accepted === "boolean" && isString(value.syncRequestId) && value.status === "queued" && isString(value.correlationId);
+}
+function isApiErrorEnvelope(value) {
+  if (!isRecord(value) || !isRecord(value.error)) {
+    return false;
+  }
+  const { code, message, correlationId, details } = value.error;
+  return typeof code === "string" && typeof message === "string" && (correlationId === void 0 || typeof correlationId === "string") && (details === void 0 || isRecord(details));
+}
+var PortalS2sClient = class {
+  baseUrl;
+  audience;
+  credential;
+  fetch;
+  randomUuid;
+  sleep;
+  constructor(options) {
+    if (typeof options.baseUrl !== "string" || !options.baseUrl.trim()) {
+      throw new TypeError("baseUrl must be a non-blank string");
+    }
+    const rawBaseUrl = options.baseUrl.trim();
+    let parsedBaseUrl;
+    try {
+      parsedBaseUrl = new URL(rawBaseUrl);
+    } catch {
+      throw new TypeError("baseUrl must be an absolute HTTPS URL");
+    }
+    const authorityStart = rawBaseUrl.indexOf("://") + 3;
+    const authoritySuffix = authorityStart >= 3 ? rawBaseUrl.slice(authorityStart) : "";
+    const authorityEndOffset = authoritySuffix.search(/[/?#]/);
+    const authority = authorityEndOffset === -1 ? authoritySuffix : authoritySuffix.slice(0, authorityEndOffset);
+    const pathAndSuffix = authorityEndOffset === -1 ? "" : authoritySuffix.slice(authorityEndOffset);
+    const hasUserInfo = authority.includes("@");
+    const hasQueryOrFragmentDelimiter = pathAndSuffix.includes("?") || pathAndSuffix.includes("#");
+    const isLoopback = parsedBaseUrl.hostname === "localhost" || parsedBaseUrl.hostname === "127.0.0.1" || parsedBaseUrl.hostname === "[::1]" || parsedBaseUrl.hostname === "::1";
+    const hasAllowedProtocol = parsedBaseUrl.protocol === "https:" || parsedBaseUrl.protocol === "http:" && isLoopback;
+    if (!hasAllowedProtocol || hasUserInfo || hasQueryOrFragmentDelimiter || parsedBaseUrl.username !== "" || parsedBaseUrl.password !== "" || parsedBaseUrl.search !== "" || parsedBaseUrl.hash !== "") {
+      throw new TypeError(
+        "baseUrl must use HTTPS (or HTTP loopback) without userinfo, query, or fragment"
+      );
+    }
+    const audience = typeof options.audience === "string" ? options.audience.trim() : "";
+    if (!audience) {
+      throw new TypeError("audience must be a non-blank string");
+    }
+    this.baseUrl = parsedBaseUrl.toString().replace(/\/+$/, "");
+    this.audience = audience;
+    this.credential = options.credential ?? defaultTokenProvider();
+    this.fetch = options.fetch ?? globalThis.fetch;
+    this.randomUuid = options.randomUuid ?? (() => globalThis.crypto.randomUUID());
+    this.sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => {
+      setTimeout(resolve, milliseconds);
+    }));
+  }
+  /**
+   * Reports what this portal instance serves and what this caller may do.
+   *
+   * Instances are self-hosted and may run an older build than this client, so
+   * call this at startup: check `operations` for the routes you rely on and
+   * `grantedRoles` for the roles you need, and fail configuration loudly rather
+   * than discovering the gap on a customer's first redeem or trial start.
+   * Requires no application role.
+   */
+  getCapabilities(appId) {
+    return this.request(
+      `/api/s2s/${S2S_API_VERSION}/apps/${encodeURIComponent(appId)}/capabilities`,
+      {},
+      200,
+      isCapabilitiesResponse
+    );
+  }
+  getSubscriptionStatus(appId, microsoftTenantId) {
+    return this.request(
+      `/api/s2s/v1/apps/${encodeURIComponent(appId)}/tenants/${encodeURIComponent(microsoftTenantId)}/subscription-status`,
+      {},
+      200,
+      isSubscriptionStatusResponse
+    );
+  }
+  getEntitlements(appId, microsoftTenantId) {
+    return this.request(
+      `/api/s2s/v1/apps/${encodeURIComponent(appId)}/tenants/${encodeURIComponent(microsoftTenantId)}/entitlements`,
+      {},
+      200,
+      isEntitlementsResponse
+    );
+  }
+  getLinkage(appId, microsoftTenantId) {
+    return this.request(
+      `/api/s2s/v1/apps/${encodeURIComponent(appId)}/tenants/${encodeURIComponent(microsoftTenantId)}/linkage`,
+      {},
+      200,
+      isLinkageResponse
+    );
+  }
+  redeemLicenseKey(appId, request) {
+    return this.request(
+      `/api/s2s/v1/apps/${encodeURIComponent(appId)}/claims/redeem-license-key`,
+      {
+        method: "POST",
+        body: request,
+        idempotencyKey: this.randomUuid()
+      },
+      200,
+      isRedeemLicenseKeyResponse
+    );
+  }
+  releaseClaim(appId, request) {
+    return this.request(
+      `/api/s2s/v1/apps/${encodeURIComponent(appId)}/claims/release`,
+      {
+        method: "POST",
+        body: request,
+        idempotencyKey: this.randomUuid()
+      },
+      200,
+      isReleaseClaimResponse
+    );
+  }
+  requestSubscriptionSync(appId, subscriptionId, request) {
+    return this.request(
+      `/api/s2s/v1/apps/${encodeURIComponent(appId)}/subscriptions/${encodeURIComponent(subscriptionId)}/sync`,
+      {
+        method: "POST",
+        body: request,
+        idempotencyKey: this.randomUuid()
+      },
+      202,
+      isSyncRequestResponse
+    );
+  }
+  startTrial(appId, microsoftTenantId, request = {}) {
+    return this.request(
+      `/api/s2s/v1/apps/${encodeURIComponent(appId)}/tenants/${encodeURIComponent(microsoftTenantId)}/trial`,
+      {
+        method: "POST",
+        body: request,
+        idempotencyKey: this.randomUuid()
+      },
+      200,
+      isStartTrialResponse
+    );
+  }
+  requestTenantSync(appId, microsoftTenantId, request) {
+    return this.request(
+      `/api/s2s/v1/apps/${encodeURIComponent(appId)}/tenants/${encodeURIComponent(microsoftTenantId)}/sync`,
+      {
+        method: "POST",
+        body: request,
+        idempotencyKey: this.randomUuid()
+      },
+      202,
+      isSyncRequestResponse
+    );
+  }
+  async request(path, options, expectedSuccessStatus, isSuccessResponse) {
+    const correlationId = this.randomUuid();
+    let accessToken;
+    try {
+      accessToken = await this.credential.getToken(`${this.audience}/.default`);
+    } catch {
+      throw new PortalS2sError({
+        code: "token_unavailable",
+        correlationId,
+        message: "Portal access token is unavailable"
+      });
+    }
+    if (!accessToken) {
+      throw new PortalS2sError({
+        code: "token_unavailable",
+        correlationId,
+        message: "Portal access token is unavailable"
+      });
+    }
+    const headers = {
+      Authorization: `Bearer ${accessToken.token}`,
+      "x-correlation-id": correlationId
+    };
+    if (options.idempotencyKey) {
+      headers["idempotency-key"] = options.idempotencyKey;
+    }
+    if (options.body !== void 0) {
+      headers["content-type"] = "application/json";
+    }
+    let serializedBody;
+    try {
+      serializedBody = options.body === void 0 ? void 0 : JSON.stringify(options.body);
+    } catch {
+      throw new PortalS2sError({
+        code: "request_serialization_failed",
+        correlationId,
+        message: "The portal request body could not be serialized."
+      });
+    }
+    let response;
+    try {
+      response = await fetchWithRetry(
+        () => this.fetch(`${this.baseUrl}${path}`, {
+          method: options.method ?? "GET",
+          headers,
+          body: serializedBody
+        }),
+        this.sleep
+      );
+    } catch (error) {
+      if (!(error instanceof TransportRetryError)) {
+        throw error;
+      }
+      throw new PortalS2sError({
+        code: "transport_error",
+        correlationId,
+        message: "Unable to reach the subscription portal."
+      });
+    }
+    let responseBody;
+    let responseBodyParsed = true;
+    try {
+      responseBody = await response.json();
+    } catch {
+      responseBodyParsed = false;
+    }
+    if (response.ok) {
+      if (responseBodyParsed && response.status === expectedSuccessStatus && isSuccessResponse(responseBody)) {
+        return responseBody;
+      }
+      throw this.unexpectedResponse(response, correlationId);
+    }
+    if (response.status === 404 && !isApiErrorEnvelope(responseBody)) {
+      throw new PortalS2sError({
+        status: response.status,
+        code: "endpoint_unavailable",
+        correlationId: response.headers.get("x-correlation-id") ?? correlationId,
+        details: { path, apiVersion: S2S_API_VERSION },
+        message: `The portal at ${this.baseUrl} does not serve ${path}. The instance is likely older than this client; check its version against the ${S2S_API_VERSION} contract.`
+      });
+    }
+    if (responseBodyParsed && isApiErrorEnvelope(responseBody)) {
+      throw new PortalS2sError({
+        status: response.status,
+        code: responseBody.error.code,
+        correlationId: responseBody.error.correlationId ?? response.headers.get("x-correlation-id") ?? correlationId,
+        details: responseBody.error.details,
+        message: responseBody.error.message
+      });
+    }
+    throw this.unexpectedResponse(response, correlationId);
+  }
+  unexpectedResponse(response, requestCorrelationId) {
+    return new PortalS2sError({
+      status: response.status,
+      code: "unexpected_response",
+      correlationId: response.headers.get("x-correlation-id") ?? requestCorrelationId,
+      message: "The subscription portal returned an unexpected response."
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PortalS2sClient,
+  PortalS2sError,
+  S2S_API_VERSION,
+  defaultTokenProvider
+});