@devsym/subscription-portal-s2s-client 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,255 @@
+interface components {
+    schemas: {
+        ApiError: {
+            error: {
+                code: string;
+                message: string;
+                correlationId: string;
+                details?: {
+                    [key: string]: unknown;
+                };
+            };
+        };
+        RedeemLicenseKeyRequest: {
+            licenseKey: string;
+            /** Format: uuid */
+            microsoftTenantId: string;
+            requestedBy?: {
+                externalUserId?: string;
+                displayName?: string;
+            };
+            correlationId?: string;
+        };
+        RedeemLicenseKeyResponse: {
+            /** @enum {string} */
+            result: "linked" | "alreadyLinked";
+            subscriptionId: string;
+            customerOrganizationId: string;
+            effectiveEntitledAppId: string;
+            status: string;
+            quantity: number;
+            ownershipAcquisitionMode: string;
+            correlationId: string;
+        };
+        ReleaseClaimRequest: {
+            /** Format: uuid */
+            subscriptionId: string;
+            /** Format: uuid */
+            microsoftTenantId: string;
+        };
+        ReleaseClaimResponse: {
+            /** @enum {string} */
+            result: "released";
+            subscriptionId?: string;
+            correlationId: string;
+        };
+        SubscriptionStatusResponse: {
+            appId: string;
+            microsoftTenantId: string;
+            customerOrganizationId?: string;
+            hasActiveEntitlement: boolean;
+            aggregateEffectiveQuantity: number;
+            subscriptions: {
+                subscriptionId: string;
+                /** @enum {string} */
+                status: "pending" | "active" | "suspended" | "canceled" | "expired" | "incomplete" | "unassigned";
+                /** @enum {string} */
+                entitlementType: "paid" | "trial" | "manual";
+                /** @enum {string} */
+                provider: "microsoft" | "paddle" | "trial" | "manual";
+                effectiveQuantity?: number;
+                lastSynchronizedOn?: string;
+                /** @description Present and true on a trial that an active paid or manual entitlement supersedes. The trial is still listed but does not contribute to aggregateEffectiveQuantity. */
+                supersededByPaid?: boolean;
+            }[];
+        };
+        CapabilitiesResponse: {
+            /**
+             * @description The S2S contract major this instance serves.
+             * @enum {string}
+             */
+            apiVersion: "v1";
+            /** @description The portal build serving the request. Present for support and diagnostics; never branch integration behaviour on it, branch on operations instead. */
+            portalVersion?: string;
+            appId: string;
+            /** @description The operationIds this instance serves. A client calling an operation absent from this list receives 404. */
+            operations: string[];
+            /** @description Roles effectively granted to the caller for this app: present both in the caller's access token and in its trusted-application record. A role missing here fails with insufficient_role when used. */
+            grantedRoles: string[];
+        };
+        EntitlementsResponse: {
+            appId: string;
+            microsoftTenantId: string;
+            customerOrganizationId?: string;
+            hasActiveEntitlement: boolean;
+            aggregateEffectiveQuantity: number;
+            items: {
+                subscriptionId: string;
+                /** @enum {string} */
+                provider: "microsoft" | "paddle" | "trial" | "manual";
+                /** @enum {string} */
+                entitlementType: "paid" | "trial" | "manual";
+                status: string;
+                effectiveQuantity?: number;
+                lastSynchronizedOn?: string;
+            }[];
+        };
+        LinkageResponse: {
+            appId: string;
+            microsoftTenantId: string;
+            customerOrganizationId?: string;
+            tenantLink?: {
+                /** @enum {string} */
+                linkSource: "activation" | "claim" | "manualAssignment" | "trial";
+                linkedOn: string;
+                isActive: boolean;
+            };
+            claims: {
+                subscriptionId: string;
+                /** @enum {string} */
+                claimState: "assigned" | "unassigned" | "released";
+            }[];
+        };
+        SubscriptionSyncRequest: {
+            reason: string;
+        };
+        TenantSyncRequest: {
+            /** @enum {string} */
+            provider: "microsoft" | "paddle";
+            reason: string;
+        };
+        StartTrialRequest: {
+            requestedBy?: {
+                externalUserId?: string;
+                displayName?: string;
+            };
+            /** Format: email */
+            beneficiaryEmail?: string;
+            displayName?: string;
+        };
+        StartTrialResponse: {
+            /** @enum {string} */
+            result: "started" | "alreadyActive";
+            subscriptionId: string;
+            customerOrganizationId: string;
+            /** @enum {string} */
+            trialMode: "timeBased" | "seatLimited";
+            /** @enum {string} */
+            trialStatus: "active";
+            trialStartOn: string;
+            trialEndOn?: string;
+            trialSeatLimit?: number;
+            trialUsage?: number;
+            correlationId: string;
+        };
+        SyncRequestResponse: {
+            accepted: boolean;
+            syncRequestId: string;
+            /** @enum {string} */
+            status: "queued";
+            correlationId: string;
+        };
+    };
+    responses: {
+        /** @description A normalized error response. */
+        ApiError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ApiError"];
+            };
+        };
+    };
+    parameters: {
+        AppId: string;
+        SubscriptionId: string;
+        MicrosoftTenantId: string;
+        CorrelationId: string;
+        IdempotencyKey: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+type TokenProvider = {
+    getToken(scope: string): Promise<{
+        token: string;
+    } | null>;
+};
+declare function defaultTokenProvider(): TokenProvider;
+
+type PortalS2sClientOptions = {
+    baseUrl: string;
+    audience: string;
+    credential?: TokenProvider;
+    fetch?: typeof globalThis.fetch;
+    randomUuid?: () => string;
+    sleep?: (milliseconds: number) => Promise<void>;
+};
+/**
+ * The S2S contract major this client speaks. Every route it calls lives under
+ * `/api/s2s/{S2S_API_VERSION}/`. The package major is locked to this value: a
+ * new contract major ships as a new client major, never as a minor.
+ */
+declare const S2S_API_VERSION = "v1";
+type RedeemLicenseKeyRequest = components["schemas"]["RedeemLicenseKeyRequest"];
+type RedeemLicenseKeyResponse = components["schemas"]["RedeemLicenseKeyResponse"];
+type ReleaseClaimRequest = components["schemas"]["ReleaseClaimRequest"];
+type ReleaseClaimResponse = components["schemas"]["ReleaseClaimResponse"];
+type SubscriptionStatusResponse = components["schemas"]["SubscriptionStatusResponse"];
+type EntitlementsResponse = components["schemas"]["EntitlementsResponse"];
+type CapabilitiesResponse = components["schemas"]["CapabilitiesResponse"];
+type LinkageResponse = components["schemas"]["LinkageResponse"];
+type SubscriptionSyncRequest = components["schemas"]["SubscriptionSyncRequest"];
+type TenantSyncRequest = components["schemas"]["TenantSyncRequest"];
+type SyncRequestResponse = components["schemas"]["SyncRequestResponse"];
+type StartTrialRequest = components["schemas"]["StartTrialRequest"];
+type StartTrialResponse = components["schemas"]["StartTrialResponse"];
+declare class PortalS2sClient {
+    private readonly baseUrl;
+    private readonly audience;
+    private readonly credential;
+    private readonly fetch;
+    private readonly randomUuid;
+    private readonly sleep;
+    constructor(options: PortalS2sClientOptions);
+    /**
+     * 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: string): Promise<CapabilitiesResponse>;
+    getSubscriptionStatus(appId: string, microsoftTenantId: string): Promise<SubscriptionStatusResponse>;
+    getEntitlements(appId: string, microsoftTenantId: string): Promise<EntitlementsResponse>;
+    getLinkage(appId: string, microsoftTenantId: string): Promise<LinkageResponse>;
+    redeemLicenseKey(appId: string, request: RedeemLicenseKeyRequest): Promise<RedeemLicenseKeyResponse>;
+    releaseClaim(appId: string, request: ReleaseClaimRequest): Promise<ReleaseClaimResponse>;
+    requestSubscriptionSync(appId: string, subscriptionId: string, request: SubscriptionSyncRequest): Promise<SyncRequestResponse>;
+    startTrial(appId: string, microsoftTenantId: string, request?: StartTrialRequest): Promise<StartTrialResponse>;
+    requestTenantSync(appId: string, microsoftTenantId: string, request: TenantSyncRequest): Promise<SyncRequestResponse>;
+    private request;
+    private unexpectedResponse;
+}
+
+type PortalS2sErrorOptions = {
+    status?: number;
+    code: string;
+    correlationId?: string;
+    details?: Record<string, unknown>;
+    message: string;
+};
+declare class PortalS2sError extends Error {
+    readonly status: number | undefined;
+    readonly code: string;
+    readonly correlationId: string | undefined;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(options: PortalS2sErrorOptions);
+}
+
+export { type CapabilitiesResponse, type EntitlementsResponse, type LinkageResponse, PortalS2sClient, type PortalS2sClientOptions, PortalS2sError, type RedeemLicenseKeyRequest, type RedeemLicenseKeyResponse, type ReleaseClaimRequest, type ReleaseClaimResponse, S2S_API_VERSION, type StartTrialRequest, type StartTrialResponse, type SubscriptionStatusResponse, type SubscriptionSyncRequest, type SyncRequestResponse, type TenantSyncRequest, type TokenProvider, defaultTokenProvider };

package/dist/index.d.ts

@@ -0,0 +1,255 @@
+interface components {
+    schemas: {
+        ApiError: {
+            error: {
+                code: string;
+                message: string;
+                correlationId: string;
+                details?: {
+                    [key: string]: unknown;
+                };
+            };
+        };
+        RedeemLicenseKeyRequest: {
+            licenseKey: string;
+            /** Format: uuid */
+            microsoftTenantId: string;
+            requestedBy?: {
+                externalUserId?: string;
+                displayName?: string;
+            };
+            correlationId?: string;
+        };
+        RedeemLicenseKeyResponse: {
+            /** @enum {string} */
+            result: "linked" | "alreadyLinked";
+            subscriptionId: string;
+            customerOrganizationId: string;
+            effectiveEntitledAppId: string;
+            status: string;
+            quantity: number;
+            ownershipAcquisitionMode: string;
+            correlationId: string;
+        };
+        ReleaseClaimRequest: {
+            /** Format: uuid */
+            subscriptionId: string;
+            /** Format: uuid */
+            microsoftTenantId: string;
+        };
+        ReleaseClaimResponse: {
+            /** @enum {string} */
+            result: "released";
+            subscriptionId?: string;
+            correlationId: string;
+        };
+        SubscriptionStatusResponse: {
+            appId: string;
+            microsoftTenantId: string;
+            customerOrganizationId?: string;
+            hasActiveEntitlement: boolean;
+            aggregateEffectiveQuantity: number;
+            subscriptions: {
+                subscriptionId: string;
+                /** @enum {string} */
+                status: "pending" | "active" | "suspended" | "canceled" | "expired" | "incomplete" | "unassigned";
+                /** @enum {string} */
+                entitlementType: "paid" | "trial" | "manual";
+                /** @enum {string} */
+                provider: "microsoft" | "paddle" | "trial" | "manual";
+                effectiveQuantity?: number;
+                lastSynchronizedOn?: string;
+                /** @description Present and true on a trial that an active paid or manual entitlement supersedes. The trial is still listed but does not contribute to aggregateEffectiveQuantity. */
+                supersededByPaid?: boolean;
+            }[];
+        };
+        CapabilitiesResponse: {
+            /**
+             * @description The S2S contract major this instance serves.
+             * @enum {string}
+             */
+            apiVersion: "v1";
+            /** @description The portal build serving the request. Present for support and diagnostics; never branch integration behaviour on it, branch on operations instead. */
+            portalVersion?: string;
+            appId: string;
+            /** @description The operationIds this instance serves. A client calling an operation absent from this list receives 404. */
+            operations: string[];
+            /** @description Roles effectively granted to the caller for this app: present both in the caller's access token and in its trusted-application record. A role missing here fails with insufficient_role when used. */
+            grantedRoles: string[];
+        };
+        EntitlementsResponse: {
+            appId: string;
+            microsoftTenantId: string;
+            customerOrganizationId?: string;
+            hasActiveEntitlement: boolean;
+            aggregateEffectiveQuantity: number;
+            items: {
+                subscriptionId: string;
+                /** @enum {string} */
+                provider: "microsoft" | "paddle" | "trial" | "manual";
+                /** @enum {string} */
+                entitlementType: "paid" | "trial" | "manual";
+                status: string;
+                effectiveQuantity?: number;
+                lastSynchronizedOn?: string;
+            }[];
+        };
+        LinkageResponse: {
+            appId: string;
+            microsoftTenantId: string;
+            customerOrganizationId?: string;
+            tenantLink?: {
+                /** @enum {string} */
+                linkSource: "activation" | "claim" | "manualAssignment" | "trial";
+                linkedOn: string;
+                isActive: boolean;
+            };
+            claims: {
+                subscriptionId: string;
+                /** @enum {string} */
+                claimState: "assigned" | "unassigned" | "released";
+            }[];
+        };
+        SubscriptionSyncRequest: {
+            reason: string;
+        };
+        TenantSyncRequest: {
+            /** @enum {string} */
+            provider: "microsoft" | "paddle";
+            reason: string;
+        };
+        StartTrialRequest: {
+            requestedBy?: {
+                externalUserId?: string;
+                displayName?: string;
+            };
+            /** Format: email */
+            beneficiaryEmail?: string;
+            displayName?: string;
+        };
+        StartTrialResponse: {
+            /** @enum {string} */
+            result: "started" | "alreadyActive";
+            subscriptionId: string;
+            customerOrganizationId: string;
+            /** @enum {string} */
+            trialMode: "timeBased" | "seatLimited";
+            /** @enum {string} */
+            trialStatus: "active";
+            trialStartOn: string;
+            trialEndOn?: string;
+            trialSeatLimit?: number;
+            trialUsage?: number;
+            correlationId: string;
+        };
+        SyncRequestResponse: {
+            accepted: boolean;
+            syncRequestId: string;
+            /** @enum {string} */
+            status: "queued";
+            correlationId: string;
+        };
+    };
+    responses: {
+        /** @description A normalized error response. */
+        ApiError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ApiError"];
+            };
+        };
+    };
+    parameters: {
+        AppId: string;
+        SubscriptionId: string;
+        MicrosoftTenantId: string;
+        CorrelationId: string;
+        IdempotencyKey: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+type TokenProvider = {
+    getToken(scope: string): Promise<{
+        token: string;
+    } | null>;
+};
+declare function defaultTokenProvider(): TokenProvider;
+
+type PortalS2sClientOptions = {
+    baseUrl: string;
+    audience: string;
+    credential?: TokenProvider;
+    fetch?: typeof globalThis.fetch;
+    randomUuid?: () => string;
+    sleep?: (milliseconds: number) => Promise<void>;
+};
+/**
+ * The S2S contract major this client speaks. Every route it calls lives under
+ * `/api/s2s/{S2S_API_VERSION}/`. The package major is locked to this value: a
+ * new contract major ships as a new client major, never as a minor.
+ */
+declare const S2S_API_VERSION = "v1";
+type RedeemLicenseKeyRequest = components["schemas"]["RedeemLicenseKeyRequest"];
+type RedeemLicenseKeyResponse = components["schemas"]["RedeemLicenseKeyResponse"];
+type ReleaseClaimRequest = components["schemas"]["ReleaseClaimRequest"];
+type ReleaseClaimResponse = components["schemas"]["ReleaseClaimResponse"];
+type SubscriptionStatusResponse = components["schemas"]["SubscriptionStatusResponse"];
+type EntitlementsResponse = components["schemas"]["EntitlementsResponse"];
+type CapabilitiesResponse = components["schemas"]["CapabilitiesResponse"];
+type LinkageResponse = components["schemas"]["LinkageResponse"];
+type SubscriptionSyncRequest = components["schemas"]["SubscriptionSyncRequest"];
+type TenantSyncRequest = components["schemas"]["TenantSyncRequest"];
+type SyncRequestResponse = components["schemas"]["SyncRequestResponse"];
+type StartTrialRequest = components["schemas"]["StartTrialRequest"];
+type StartTrialResponse = components["schemas"]["StartTrialResponse"];
+declare class PortalS2sClient {
+    private readonly baseUrl;
+    private readonly audience;
+    private readonly credential;
+    private readonly fetch;
+    private readonly randomUuid;
+    private readonly sleep;
+    constructor(options: PortalS2sClientOptions);
+    /**
+     * 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: string): Promise<CapabilitiesResponse>;
+    getSubscriptionStatus(appId: string, microsoftTenantId: string): Promise<SubscriptionStatusResponse>;
+    getEntitlements(appId: string, microsoftTenantId: string): Promise<EntitlementsResponse>;
+    getLinkage(appId: string, microsoftTenantId: string): Promise<LinkageResponse>;
+    redeemLicenseKey(appId: string, request: RedeemLicenseKeyRequest): Promise<RedeemLicenseKeyResponse>;
+    releaseClaim(appId: string, request: ReleaseClaimRequest): Promise<ReleaseClaimResponse>;
+    requestSubscriptionSync(appId: string, subscriptionId: string, request: SubscriptionSyncRequest): Promise<SyncRequestResponse>;
+    startTrial(appId: string, microsoftTenantId: string, request?: StartTrialRequest): Promise<StartTrialResponse>;
+    requestTenantSync(appId: string, microsoftTenantId: string, request: TenantSyncRequest): Promise<SyncRequestResponse>;
+    private request;
+    private unexpectedResponse;
+}
+
+type PortalS2sErrorOptions = {
+    status?: number;
+    code: string;
+    correlationId?: string;
+    details?: Record<string, unknown>;
+    message: string;
+};
+declare class PortalS2sError extends Error {
+    readonly status: number | undefined;
+    readonly code: string;
+    readonly correlationId: string | undefined;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(options: PortalS2sErrorOptions);
+}
+
+export { type CapabilitiesResponse, type EntitlementsResponse, type LinkageResponse, PortalS2sClient, type PortalS2sClientOptions, PortalS2sError, type RedeemLicenseKeyRequest, type RedeemLicenseKeyResponse, type ReleaseClaimRequest, type ReleaseClaimResponse, S2S_API_VERSION, type StartTrialRequest, type StartTrialResponse, type SubscriptionStatusResponse, type SubscriptionSyncRequest, type SyncRequestResponse, type TenantSyncRequest, type TokenProvider, defaultTokenProvider };