@licensespring/node-sdk 1.0.10 → 1.1.0-alpha

package/README.md

@@ -105,20 +105,59 @@ deactivateLicense(payload: LicenseIdentificator): Promise<boolean>
 
 #### Activate License Offline
 
-[https://docs.licensespring.com/license-api/activation-deactivation/offline-activation](https://docs.licensespring.com/license-api/activation-deactivation/offline-activation)
+```typescript
+createOfflineActivationPayload(payload: CreateOfflineActivationRequestPayload): string
+
+checkOfflineActivationResponse(payload: string): LicenseResponseOffline
+```
+
+First create an offline request payload, which can be stored in a file:
+
+```typescript
+const offlineActivationPayload = licenseAPI.createOfflineActivationPayload({
+  'license_key': 'AAAA-0000-1111-2222',
+  'product': 'productcode',
+  'hardware_id': 'a0b1c2d3',
+});
+
+nodeFs.writeFileSync('activate_offline.req', offlineActivationPayload);
+```
+
+This file is then uploaded to the [https://docs.licensespring.com/portals/offline](Offline Portal). If the file is valid, the system will activate the license. This will also generate an `ls_activation.lic` file, which you can forward to your offline application and verify it locally.
+
+The contents of this file are verified using `checkOfflineActivationResponse`, for example:
 
 ```typescript
-activateOffline(payload: LicenseActivationIdentificatorOfflineWithVariables): Promise<LicenseResponseOffline>
+const activationResponse = nodeFs.readFileSync('ls_activation.lic');
+
+try {
+  return licenseAPI.checkOfflineActivationResponse(activationResponse);
+} catch (error) {
+  return false;
+}
 ```
 
 #### Deactivate License Offline
 
-[https://docs.licensespring.com/license-api/activation-deactivation/offline-deactivation](https://docs.licensespring.com/license-api/activation-deactivation/offline-deactivation)
 
 ```typescript
-deactivateOffline(payload: LicenseIdentificator): Promise<boolean>
+createOfflineDectivationPayload(payload: CreateOfflineActivationRequestPayload): string
+```
+
+First create an offline request payload, which can be stored in a file:
+
+```typescript
+const offlineDectivationPayload = licenseAPI.createOfflineDectivationPayload({
+  'license_key': 'AAAA-0000-1111-2222',
+  'product': 'productcode',
+  'hardware_id': 'a0b1c2d3',
+});
+
+nodeFs.writeFileSync('deactivate_offline.req', offlineDectivationPayload);
 ```
 
+This file is then uploaded to the [https://docs.licensespring.com/portals/offline](Offline Portal). If the file is valid, the system will deactivate the license.
+
 #### Get Trial License Key
 
 [https://docs.licensespring.com/license-api/trial-key](https://docs.licensespring.com/license-api/trial-key)
@@ -356,20 +395,54 @@ deactivateLicense(payload: Managed<LicenseIdentificator>): Promise<boolean>
 
 #### Activate License Offline
 
-[https://docs.licensespring.com/license-api/activation-deactivation/offline-activation](https://docs.licensespring.com/license-api/activation-deactivation/offline-activation)
+```typescript
+createOfflineActivationPayload(payload: Managed<CreateOfflineActivationRequestPayload>): string
 
-```javascript
-activateOffline(payload: Managed<LicenseIdentificatorOfflineWithVariables>): Promise<LicenseResponseOffline>
+activateOffline(payload: string): LicenseResponseOffline
+```
+
+First create an offline request payload, which can be stored in a file:
+
+```typescript
+const offlineActivationPayload = licenseManager.createOfflineActivationPayload({
+  'license_key': 'AAAA-0000-1111-2222'
+});
+
+nodeFs.writeFileSync('activate_offline.req', offlineActivationPayload);
+```
+
+This file is then uploaded to the [https://docs.licensespring.com/portals/offline](Offline Portal). If the file is valid, the system will activate the license. This will also generate an `ls_activation.lic` file, which you can forward to your offline application.
+
+You can then pass the contents of this `ls_activation.lic` file to `activateOffline` which will verify the file response and (if valid) apply the activation locally. For example:
+
+```typescript
+const activationResponse = nodeFs.readFileSync('ls_activation.lic');
+activateOffline(activationResponse);
 ```
 
 #### Deactivate License Offline
 
-[https://docs.licensespring.com/license-api/activation-deactivation/offline-deactivation](https://docs.licensespring.com/license-api/activation-deactivation/offline-deactivation)
 
-```javascript
-deactivateOffline(payload: Managed<LicenseIdentificator>): Promise<boolean>
+```typescript
+createOfflineDectivationPayload(payload: Managed<CreateOfflineActivationRequestPayload>): string
+
+deactivateOffline(): void
 ```
 
+First create an offline request payload, which can be stored in a file:
+
+```typescript
+const offlineDectivationPayload = licenseManager.createOfflineDectivationPayload({
+  'license_key': 'AAAA-0000-1111-2222'
+});
+
+nodeFs.writeFileSync('deactivate_offline.req', offlineDectivationPayload);
+```
+
+This file is then uploaded to the [https://docs.licensespring.com/portals/offline](Offline Portal). If the file is valid, the system will deactivate the license.
+
+To apply the license deactivation locally, you can call `licenseManager.deactivateOffline()`.
+
 #### Get Trial License Key
 
 [https://docs.licensespring.com/license-api/trial-key](https://docs.licensespring.com/license-api/trial-key)
@@ -924,562 +997,6 @@ export type LicensespringFloatingConfigDef = Omit<LicensespringFloatingConfig, '
   hardwareIDMethod?: number,
 };
 
-type LicenseIdentificatorKeyBased = {
-  license_key: string,
-};
-
-type LicenseIdentificatorUserBased = {
-  username: string,
-};
-
-type LicenseActivationIdentificatorUserBased = {
-  username: string,
-  password: string,
-};
-
-type LicenseIdentificatorUserSSOBased = ({
-  id_token: string,
-} | {
-  code: string,
-}) & {
-  customer_account_code: string,
-};
-
-export type SSOURLParams = {
-  product: string,
-  type: 'token'|'code',
-};
-
-type LicenseIdentificatiorRequired = {
-  hardware_id: string,
-  product: string,
-  bundle_code?: string,
-  license_id?: number,
-};
-
-export type LicenseActivationIdentificatorWithVariables = LicenseActivationIdentificator & { variables?: Dictionary<string> };
-export type LicenseActivationIdentificatorOfflineWithVariables = LicenseActivationIdentificator & OfflineActivationRequest & { variables?: Dictionary<string> };
-
-export type LicenseIdentificatorWithVariables = LicenseIdentificator & { variables?: Dictionary<string> };
-
-export type LicenseIdentificatorOfflineWithVariables = LicenseIdentificator & OfflineActivationRequest & { variables?: Dictionary<string> };
-
-export type TrialKeyPayload = { email: string, product: string, hardware_id: string };
-
-export type GetUserLicensesPayload = { username: string, password: string, product: string };
-
-export type GetCustomerLicensesPayload = { customer: string, product: string };
-
-export type LicenseIdentificatorAndFeature = LicenseIdentificator & { feature: string };
-
-export type LicenseIdentificatorAddConsumptions = LicenseIdentificator & { consumptions: number };
-
-export type LicenseIdentificatorAddFeatureConsumptions = LicenseIdentificator & { feature: string, consumptions: number };
-
-export type ProductDetailsPayload = {
-  product: string,
-  /** @defaultValue false */
-  include_expired_features?: boolean,
-  /** @defaultValue false */
-  include_latest_version?: boolean,
-  /** @defaultValue false */
-  include_custom_fields?: boolean,
-}
-
-export type LicenseIdentificatorWithBorrowedUntil = LicenseIdentificator & { borrowed_until: DateInputString };
-
-export type PasswordChangePayload = { username: string, password: string, new_password: string };
-
-export type LicenseIdentificatorWithInstallation = LicenseIdentificator & { env: string, channel: string, version: string };
-
-export type Managed<T> = Omit<T, 'product' | 'hardware_id'>;
-
-/**
- * @type {LicenseIdentificator}
- *
- * An object that identifies a License using either a license-key, user credentials or single sign-on credentials.
- * Optionally can include a `license_id` property to force a specific license is being selected.
- */
-export type LicenseIdentificator = (
-  XOR<LicenseIdentificatorKeyBased, LicenseIdentificatorUserBased>
-) & LicenseIdentificatiorRequired;
-
-export type LicenseActivationIdentificator = (
-  XOR<LicenseIdentificatorKeyBased, LicenseActivationIdentificatorUserBased, LicenseIdentificatorUserSSOBased>
-) & LicenseIdentificatiorRequired;
-
-/**
- * @type {LicenseUser}
- *
- * An object describing a User associated to a specific license
- */
-export type LicenseUser = {
-  id: number,
-  email: string,
-  first_name: string,
-  last_name: string,
-  phone_number: string,
-  is_initial_password: boolean,
-  allow_unlimited_activations: boolean,
-  max_activations: number,
-  total_activations: number,
-};
-
-/**
- * @type {ProductDetails}
- *
- * An object describing the basic properties of a Product
- */
-export type ProductDetails = {
-  product_id: number,
-  product_name: string,
-  short_code: string,
-  authorization_method: 'license-key' | 'user',
-  metadata: JSON,
-};
-
-/**
- * @type {Customer}
- *
- * An object describing a Customer
- */
-export type Customer = {
-  email: string,
-  company_name: string,
-  reference: string,
-  phone: string,
-  first_name: string,
-  last_name: string,
-  city: string,
-  postcode: string,
-  state: string,
-  country: string,
-  address: string,
-  customer_account: string|null,
-  metadata: JSON,
-};
-
-/**
- * @type {CustomField}
- *
- * An object describing a Custom Field. These are key-value pairs assigned to a Product and inherited by that product's Licenses. They can be overriden on the License level
- */
-export type CustomField = {
-  name: string,
-  data_type: 'numer' | 'text' | 'date/time',
-  value: string,
-};
-
-/**
- * @type {ProductFeature}
- *
- * An object describing a Product Feature. These are custom attributes assigned to a Product and inherited by that product's Licenses
- */
-export type ProductFeature = {
-  id: number,
-  code: string,
-  name: string,
-  expiry_date: string,
-  metadata: JSON,
-  is_floating_cloud: boolean,
-} & XOR<{
-  feature_type: 'activation',
-}, {
-  feature_type: 'consumption',
-  max_consumption: number,
-  allow_unlimited_consumptions: boolean,
-  total_consumptions: number,
-  allow_overages: number,
-  max_overages: number,
-  reset_consumption: boolean,
-  consumption_period: 'daily' | 'weekly' | 'monthly' | 'annualy' | null,
-}> & XOR<{
-  is_floating: false
-}, {
-  is_floating: true,
-  floating_users: number,
-  floating_timeout?: number,
-}>;
-
-/**
- * @type {LicenseType}
- *
- * Declares the type of License which is always one of the following:
- *
- * - *perpetual*: A perpetual license does not expire. The `is_expired` field on such a license will always be `false`.
- * Note that a perpetual *trial* license (`is_trial` flag is set to `true`) does have an `validity_period`, which refers to the end of the trial period.
- *
- * - *time-limited*: Has a `validity_period` set as a calendar date. After the date has passed, the `is_expired` flag will be set to `true`.
- *
- * - *subscription*: Uses an external source of truth such as a 3rd party service to determine the state of the License.
- *
- * - *consumption*: Permits usage metering. These licenses set a value the vendor wishes to meter, and then record the times that resource has been used.
- * Includes the following properties: `max_consumptions`, `total_consumptions`, `allow_unlimited_consumptions`, `allow_overages`, `max_overages`, `reset_consumption` and `consumption_period`.
- *
- */
-export type LicenseType = 'perpetual' | 'time-limited' | 'consumption' | 'subscription';
-
-/**
- * @type {LicenseResponse}
- *
- * The License object received as a response when checking or activating a License. Includes a set of common properties and additional ones which may or may not appear depending on `license_type`, `is_trial`, `is_floating`/`is_floating_cloud` and Product `authorization_method` (key-based vs. user based).
- */
-export type LicenseResponse = {
-  id: number;
-  allow_grace_period: boolean,
-  allow_overages: boolean,
-  allow_unlimited_activations: boolean,
-  borrowed_until: string | null,
-  can_borrow: boolean,
-  channel: string,
-  device_id: number,
-  enable_maintenance_period: boolean
-  environment: string,
-  eula_link: string,
-  floating_timeout: number,
-  grace_period: number,
-  hash_md5: string,
-  installation_file: string,
-  is_air_gapped: boolean,
-  is_borrowed: boolean,
-  is_expired: boolean,
-  is_hardware_key_auth: boolean,
-  license_active: boolean,
-  license_enabled: boolean,
-  license_signature: string,
-  license_type: LicenseType,
-  maintenance_period: string | null,
-  max_activations: number,
-  max_borrow_time: number,
-  max_license_users: number,
-  max_overages: number,
-  max_transfers: number,
-  order_store_id: string,
-  prevent_vm: boolean,
-  release_date: string,
-  release_notes_link: string,
-  requires_version: string,
-  size: string,
-  start_date: string | null,
-  times_activated: number,
-  transfer_count: number,
-  validity_period: DateISO8601UTC | null,
-  version: string,
-  product_features: ProductFeature[],
-  custom_fields: CustomField[],
-  customer: Customer,
-  product_details: ProductDetails,
-  metadata: JSON,
-}
-& XOR<{
-  license_key: string,
-}, {
-  user: LicenseUser,
-}>
-& XOR<({
-  is_floating: true,
-  is_floating_cloud: boolean,
-  floating_in_use_devices: number,
-} | {
-  is_floating: boolean,
-  is_floating_cloud: true,
-  floating_in_use_devices: number,
-}) & {
-  floating_users: number,
-},
-{
-  is_floating_cloud: false,
-  is_floating: false,
-}>
-& XOR<{
-  is_trial: false,
-}, {
-  is_trial: true,
-  trial_days: number,
-}>
-& XOR<{
-  license_type: 'consumption',
-  max_consumptions: number,
-  total_consumptions: number,
-  allow_unlimited_consumptions: boolean,
-  allow_overages: boolean,
-  max_overages: number,
-  reset_consumption: boolean,
-  consumption_period: 'daily' | 'weekly' | 'monthly' | 'annually' | null,
-},
-{}
->;
-
-/**
- * @type {LicenseResponseOffline}
- *
- * The License object received as a response when activating a License using the Offline method.
- * This type is equal to LicenseResponse with the addition of the `license_signature_v2` property.
- */
-export type LicenseResponseOffline = LicenseResponse & {
-  license_signature_v2: string,
-};
-
-export type LicenseFilePayload = LicenseResponseOffline & {
-  offline_signature: string,
-};
-
-export type OfflineActivationRequest = {
-  prefix?: string;
-  os_ver?: string;
-  sdk_build_version?: string;
-  hostname?: string;
-  ip?: string;
-  external_ip?: string;
-  app_ver?: string;
-  mac_address?: string;
-};
-
-export type DeviceVariable = {
-  id: number,
-  device_id: number,
-  created_at: DateISO8601UTC,
-  variable: string,
-  value: string,
-};
-
-type LicenseTrialExisting = {
-};
-
-type LicenseTrialNewCommon = {
-  license_key: string,
-  id: number,
-  order_id: number,
-  product_id: number,
-  max_license_users: number,
-  max_activations: number,
-  times_activated: number,
-  is_trial: true,
-  active: boolean,
-  enabled: boolean,
-  max_transfers: number,
-  trial_days: number,
-  maintenance_duration: TimeLength | null,
-  validity_period: DateISO8601UTC | null,
-  enable_maintenance_period: boolean,
-  prevent_vm: boolean,
-  is_hardware_key_auth: boolean,
-  license_user: string,
-  initial_password: string,
-  metadata: JSON,
-  created_at: number,
-  updated_at: number,
-  LicenseProductFeatures: LicenseProductFeature[],
-  LicenseCustomFields: {
-    product_custom_field_id: number,
-    value: string
-  }[],
-};
-
-type LicenseTrialNew = LicenseTrialNewCommon
-  & (XOR<
-  {
-    is_floating_cloud: true,
-    floating_users: number,
-    floating_timeout: number,
-  },
-  {}
-  >)
-  & (XOR<
-    {
-      license_type: 'consumption',
-      allow_overages: boolean,
-      max_overages: number,
-      max_consumptions: number,
-      valid_duration: null,
-      consumption_period: 'daily' | 'weekly' | 'monthly' | 'annually' | null,
-      reset_consumption: boolean,
-    },
-    XOR<
-    {
-      license_type: 'subscription',
-      grace_period: number,
-      allow_grace_period: boolean,
-    },
-    {
-      license_type: 'perpetual' | 'time-limited',
-    }
-    >
-  >
-);
-
-export type LicenseTrialResponse = (LicenseTrialNew | LicenseTrialExisting) & {
-  license_type: LicenseType,
-  is_trial: boolean,
-  /** Username */
-  license_user: string,
-};
-
-type CustomerLicenseUser = {
-  email: string,
-  is_active: boolean,
-  first_name: string,
-  last_name: string,
-  phone_number: string,
-  is_initial_password: boolean,
-  initial_password: string,
-  max_activations: number,
-  total_activations: number,
-  license_id: number,
-  order_id: number,
-  order_store_id: string,
-};
-
-export type CustomerLicenseUsersResponse = {
-  customer: {
-    email: string | null,
-    first_name: string | null,
-    last_name: string | null,
-    company_name: string | null,
-    phone: string | null,
-    reference: string | null,
-    address: string | null,
-    postcode: string | null,
-    city: string | null,
-    country: string | null,
-    state: string | null,
-    customer_account: null | {
-      id: string,
-      name: string,
-      code: string,
-    },
-    metadata: JSON,
-  },
-  users: CustomerLicenseUser[]
-};
-
-export type LicenseFeatureResponse = {
-  id: number,
-  code: string,
-  name: string,
-  floating_timeout: number | null,
-  floating_users: number | null,
-  feature_type: 'activation' | 'consumption'
-  expiry_date: DateISO8601UTC | null,
-  metadata: JSON,
-  is_floating: boolean,
-  is_floating_cloud: boolean,
-  floating_in_use_devices: number,
-  license_id: number,
-};
-
-export type LicenseProductFeature = {
-  id: number,
-  product_feature_id: number,
-  max_consumption: number,
-  allow_overages: boolean,
-  max_overages: number,
-  reset_consumption: number,
-  consumption_period: 'daily' | 'weekly' | 'monthly' | 'annually' | null,
-  expiry_date: DateISO8601UTC | null,
-  is_floating: boolean,
-  is_floating_cloud: boolean,
-  metadata: JSON,
-} & XOR<({ is_floating: true } | { is_floating_cloud: true }) & {
-  floating_timeout: number,
-  floating_users: number,
-},
-{}>;
-
-export type LicenseConsumptionsResponse = {
-  id: number,
-  max_consumptions: number,
-  total_consumptions: number,
-  allow_unlimited_consumptions: boolean,
-  allow_negative_consumptions: boolean,
-  allow_overages: boolean,
-  max_overages: number,
-  reset_consumption: boolean,
-  consumption_period: 'daily' | 'weekly' | 'monthly' | 'annually' | null,
-};
-
-export type LicenseFeatureConsumptionResponse = {
-  allow_negative_consumptions: boolean,
-  allow_overages: boolean,
-  allow_unlimited_consumptions: boolean,
-  consumption_period: 'daily' | 'weekly' | 'monthly' | 'annually' | null,
-  is_floating_cloud: boolean,
-  is_floating: boolean,
-  max_consumptions: number,
-  max_overages: number,
-  reset_consumption: boolean,
-  total_consumptions: number,
-
-  // the following properties are only present on floating and floating cloud features:
- floating_timeout?: number | null,
- floating_users?: number,
-};
-
-export type ProductDetailsResponse = ProductDetails & {
-  floating_timeout: number,
-  max_overages: number,
-  trial_days: number,
-  allow_overages: boolean,
-  allow_trial: boolean,
-  prevent_vm: boolean,
-  custom_fields: {
-    id: number,
-    name: string,
-    default_value: string,
-  }[],
-  latest_version: null | (InstallationFileBase & {
-    id: number,
-    product_id: number,
-    enabled: boolean,
-    created_at: DateISO8601UTC,
-    updated_at: DateISO8601UTC,
-    full_link: string | null,
-    filename: string | null,
-  })
-};
-
-export type LicenseBorrowResponse = {
-  license_id: number,
-  device_id: number,
-  borrowed_until: DateInputString,
-  max_borrow_time: number,
-};
-
-type InstallationFileBase = {
-  version: string | null,
-  environment: string | null,
-  hash_md5: string | null,
-  eula_link: string | null,
-  release_notes_link: string | null,
-  size: string | null,
-  requires_version: string | null,
-  channel: string | null,
-  release_date: DateISO8601UTC | null,
-};
-
-export type InstallationFileResponse = InstallationFileBase & {
-  installation_file: string | null
-};
-
-export type VersionsResponse = {
-  version: string,
-  release_date: DateISO8601UTC,
-}[];
-
-export type LicenseDataMethod = 'check_license'
-  |'activate_license'
-  |'activate_license_offline'
-  |'activate_air_gap'
-  |'update_license_offline'
-  |'product_details'
-  |'device_variables'
-  |'normal'
-  |'license_consumption'
-  |'feature_consumption'
-  |'register_feature'
-  |'floating_server_register'
-;
-
 export enum HardwareIdAlgorithm {
   Default = 0,
   WindowsHardwareFingerprintId = 1,