Merge pull request #145 from Salable/feat/subscriptions-manage-seats

feat: new subscriptions manageSeats method

Author: avst-perrygeorge

docs/docs/subscriptions/manage-seats.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 13
+---
+
+# Manage Seats
+
+Assign, unassign and replace grantees on seats.
+
+## Code Sample
+
+```typescript
+import { Salable } from '@salable/node-sdk';
+
+const salable = new Salable('{{API_KEY}}', 'v2');
+
+await salable.subscriptions.manageSeats('17830730-3214-4dda-8306-9bb8ae0e3a11', [
+  {
+    type: 'assign',
+    granteeId: 'userId_1'
+  },
+  {
+    type: 'unassign',
+    granteeId: 'userId_2'
+  },
+  {
+    type: 'replace',
+    granteeId: 'userId_3',
+    newGranteeId: 'userId_4',
+  }
+]);
+```
+
+## Parameters
+
+#### subscriptionUuid (_required_)
+
+_Type:_ `string`
+
+The UUID of the Subscription
+
+#### Options (_required_)
+
+_Type:_ `ManageSeatOptions[]`
+
+| Option       | Type   | Description                                                                                                                                                                                                                               | Required |
+|--------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+| type         | enum   | `assign`: Will assign an empty seat to the provided granteeId. `unassign`: Will unassign the seat from the provided granteeId. `replace`: Unassigns the seat from the provided granteeId and then assigns it to the `newGranteeId` value. | ✅        |
+| granteeId    | string | The granteeId the action is being performed on.                                                                                                                                                                                           | ✅        |
+| newGranteeId | string | Only applicable to the `replace` action. The new granteeId on the seat.                                                                                                                                                                   | ❌  |
+
+## Return Type
+
+For more information about this request, see our API documentation on [subscription manage seats](https://docs.salable.app/api/v2#tag/Subscriptions/operation/manageSubscriptionSeats)

src/licenses/index.ts

@@ -118,9 +118,9 @@ export type LicenseVersions = {
      * @param {CheckLicenseInput} options.granteeIds - The grantee IDs to check the license for
      * @param {CheckLicenseInput} options.grace - (Optional) The number of days to extend the end dates of capabilities
      *
-     * @returns {Promise<CheckLicensesCapabilitiesResponse>} The capabilities of the license passed
+     * @returns {Promise<CheckLicensesCapabilitiesResponse | void>} The capabilities of the license passed
      */
-    check: (options: CheckLicenseInput) => Promise<CheckLicensesCapabilitiesResponse>;
+    check: (options: CheckLicenseInput) => Promise<CheckLicensesCapabilitiesResponse | void>;
   };
 };
 

src/licenses/v2/licenses-v2.test.ts

@@ -229,6 +229,15 @@ describe('Licenses V2 Tests', () => {
       }),
     );
   });
+
+  it('check: Should return undefined if grantee is not licensed', async () => {
+    const data = await salable.licenses.check({
+      productUuid: testUuids.productUuid,
+      granteeIds: ['not-licensed-grantee'],
+    });
+
+    expect(data).toBeUndefined();
+  });
 });
 
 const licenseCapabilitySchema: Capability = {

src/subscriptions/index.ts

@@ -13,7 +13,7 @@ import {
   GetAllInvoicesOptions,
   UpdateSubscriptionInput,
   GetSubscriptionSeatsOptions,
-  PaginatedSeats, GetSeatCountResponse
+  PaginatedSeats, GetSeatCountResponse, ManageSeatOptions
 } from '../types';
 import { v2SubscriptionMethods } from './v2';
 
@@ -195,6 +195,20 @@ export type SubscriptionVersions = {
      */
     reactivateSubscription: (subscriptionUuid: string) => Promise<void>;
 
+    /**
+     *  Manage seats on a subscription
+     *
+     *  @param {string} subscriptionUuid - The UUID of the subscription
+     *
+     * Docs - https://docs.salable.app/api/v2#tag/Subscriptions/operation/manageSubscriptionSeats
+     *
+     * @returns {Promise<void>}
+     */
+    manageSeats: (
+      subscriptionUuid: string,
+      options: ManageSeatOptions[],
+    ) => Promise<void>;
+
     /**
      *  Incrementing will create unassigned licenses.
      *

src/subscriptions/v2/index.ts

@@ -20,6 +20,7 @@ export const v2SubscriptionMethods = (request: ApiRequest): SubscriptionVersions
   getCancelSubscriptionLink: (uuid) => request(getUrl(`${baseUrl}/${uuid}/cancelpaymentlink`, {}), { method: 'GET' }),
   getPaymentMethod: (uuid) => request(getUrl(`${baseUrl}/${uuid}/payment-method`, {}), { method: 'GET' }),
   reactivateSubscription: (uuid) => request(getUrl(`${baseUrl}/${uuid}/reactivate`, {}), { method: 'PUT' }),
+  manageSeats: (uuid, options) => request(`${baseUrl}/${uuid}/manage-seats`, { method: 'PUT', body: JSON.stringify(options) }),
   addSeats: (uuid, options) => request(`${baseUrl}/${uuid}/seats`, { method: 'POST', body: JSON.stringify(options) }),
   removeSeats: (uuid, options) =>
     request(getUrl(`${baseUrl}/${uuid}/seats`, {}), {

src/subscriptions/v2/subscriptions-v2.test.ts

@@ -7,7 +7,7 @@ import {
   Subscription,
   PaginatedSubscriptionInvoice,
   Version,
-  PaginatedLicenses, Capability, License
+  PaginatedLicenses, Capability, License, SeatActionType
 } from '../../types';
 import getEndTime from '../../../test-utils/helpers/get-end-time';
 import { v4 as uuidv4 } from 'uuid';
@@ -193,6 +193,16 @@ describe('Subscriptions V2 Tests', () => {
     expect(data).toBeUndefined();
   });
 
+  it('manageSeats: Should successfully perform multiple seat actions', async () => {
+    const data = await salable.subscriptions.manageSeats(perSeatSubscriptionUuid, [
+      { type: SeatActionType.assign, granteeId: 'assign_grantee_id' },
+      { type: SeatActionType.unassign, granteeId: 'userId_0' },
+      { type: SeatActionType.replace, granteeId: 'userId_1', newGranteeId: 'replace_grantee_id' },
+    ]);
+
+    expect(data).toBeUndefined();
+  });
+
   it('addSeats: Should successfully add seats to the subscription', async () => {
     const data = await salable.subscriptions.addSeats(perSeatSubscriptionUuid, {
       increment: 1,

src/types.ts

@@ -175,6 +175,24 @@ export type PaginatedSeats = {
   data: Seat[];
 };
 
+
+export enum SeatActionType {
+  assign = 'assign',
+  unassign = 'unassign',
+  replace = 'replace',
+}
+
+export type ManageSeatOptions =
+  | {
+  type: SeatActionType.assign | SeatActionType.unassign;
+  granteeId: string;
+}
+  | {
+  type: SeatActionType.replace;
+  granteeId: string;
+  newGranteeId: string;
+};
+
 export type Subscription = {
   uuid: string;
   paymentIntegrationSubscriptionId: string;