@voucherify/sdk 3.0.0 → 3.0.2

package/README.md

@@ -5,34 +5,70 @@
 <h3 align="center">Official <a href="https://www.voucherify.io">Voucherify</a> JS SDK</h3>
 
 <p>
-    <a href="#"><img src="https://github.com/voucherifyio/voucherify-js-sdk/workflows/Release/badge.svg?branch=main" alt="Build Status"/></a>
     <a href="#"><img src="https://img.shields.io/npm/v/@voucherify/sdk?label=SDK" alt="SDK NPM Version"/></a>
     <a href="#"><img src="https://img.shields.io/npm/dm/@voucherify/sdk?label=SDK%20downloads" alt="SDK NPM Downloads"/></a>
 </p>
 <hr/>
 
-Voucherify empowers marketers and developers with flexible building blocks to come up with, implement, and track targeted promotional campaigns.
+## 👋 Intro
 
-Learn more about Voucherify by visiting [our site](https://www.voucherify.io).
+Voucherify is an Incentive Optimization Engine that helps digital teams launch, test, and optimize targeted incentives – from coupons and promotions to loyalty programs and personalized offers – all with API.
 
-This SDK is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) based on our [Documentation](https://docs.voucherify.io/docs/introduction) with v2018-08-01 version.
+We build Voucherify so you can run fewer incentives, but better ones.
 
-The legacy version of JS SDK could be found [here](https://github.com/voucherifyio/voucherify-js-sdk)
+**Launch fast.**
 
-## 📝 Documentation
+**Test every day.**
 
-You will find detailed description and example responses at our [official documentation](https://docs.voucherify.io/reference). Most method headers point to more detailed descriptions of arguments you can use.
+**Drop what doesn’t work.**
 
-📚 Want to learn more? Visit our [official site](https://www.voucherify.io) or our [Success Portal](https://success.voucherify.io).
+**And optimize what does.**
 
-👽 Having troubles? Check our [Help center](https://support.voucherify.io/).
+Integrate easily with your existing stack to make experimentation and optimization effortless.
 
-🧪 Looking for promotion ideas? Check our [Cookbook](https://cookbook.voucherify.io/) to get an inspiration.
+## 📝 Useful info
 
-🐛 Encounter a bug? Please file a report in the [Issues](https://github.com/voucherifyio/voucherify-js-sdk/issues).
+This SDK is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) based on Voucherify [API reference](https://docs.voucherify.io/api-reference/introduction-api), `v2018-08-01` version.
 
+If needed, visit the [legacy JS SDK](https://github.com/voucherifyio/voucherify-js-sdk/tree/%40voucherify/sdk%402.9.4 "Legacy JS SDK, version 2.9.4")
 
-## ⚙️ Installation
+For more info, visit those places:
+- ✅ [Supported endpoints](./ENDPOINTS-COVERAGE.md).
+- 📘 [API docs](https://docs.voucherify.io/api-reference/introduction-api "Voucherify API documentation").
+- 🧑‍🍳 [Promotion cookbook](https://www.voucherify.io/promotion-examples "Explore promotion examples").
+- 💬 [Help center](https://support.voucherify.io "Voucherify dashboard documentation").
+- 🐛 Caught a bug? [Add an issue](https://github.com/voucherifyio/voucherify-js-sdk/issues "Visit issues in Voucherify JS SDK")!
+- 🧑‍💻 Need help? [Contact support](https://www.voucherify.io/contact-support "Visit contact support page").
+
+## 🔄 JS SDK versions: v2 and v3
+
+The v2 and v3 JS SDK version differ in:
+
+- **Language and generation:**
+    - v2: hand-written in TypeScript.
+    - v3: auto-generated from the OpenAPI definition and written in JavaScript.
+- **Types:**
+    - v2: built-in TypeScript types.
+    - v3: **Includes built-in TypeScript definitions (starting from v3.0.1).** Although written in JS, the SDK now ships with type declarations generated from JSDoc. Each generated model/class also exposes a `validateJSON` method to verify data shape/types at runtime.
+- **Client creation and auth:**
+    - v2: different client initialization and API key handling.
+    - v3: a new way to configure the API client and provide API keys (see [Get your keys and address](#-get-your-keys-and-address) and [Run code](#-run-code)).
+- **API coverage:**
+    - v2: limited and historically maintained.
+    - v3: supports all non-deprecated endpoints. We strongly recommend using v3.
+
+### 🧭 Quick migration guide
+
+To migrate from v2 to v3:
+
+- **Install:** you can install v3 under an alias to migrate gradually (see [Install](#️-install) section).
+- **Initialization:** update client creation and key/basePath setup as shown in [Run code](#-run-code).
+- **Types:** ensure you are using **v3.0.1 or later** to leverage the included TypeScript definitions automatically. You no longer need to create custom `.d.ts` files. You can still use the models’ `validateJSON` methods for extra runtime validation.
+- **Endpoints:** review [ENDPOINTS-COVERAGE.md](./ENDPOINTS-COVERAGE.md) and switch calls to their v3 equivalents. Avoid deprecated endpoints — v3 covers active ones only.
+
+## ⚙️ Install
+
+Use any of the following methods to install the SDK.
 
 ### For [Node.js](https://nodejs.org/)
 
@@ -48,32 +84,61 @@ If you’re still using the previous SDK (v2.x.x), you can install the new versi
 npm install @voucherify/newsdk@npm:@voucherify/sdk@^3.0.0
 ```
 
-### 🚀 Running code
-
-Please follow the [installation](#installation) instruction and execute the following JS code:
-
-```javascript
-const Voucherify = require("@voucherify/sdk");
-
-const defaultClient = Voucherify.ApiClient.instance;
-// Configure the server url
-defaultClient.basePath = "https://{cluster}.api.voucherify.io";
-// Configure API key authorization: X-App-Id
-const XAppId = defaultClient.authentications["X-App-Id"];
-XAppId.apiKey = "YOUR APP ID";
-// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
-//X-App-Id.apiKeyPrefix['X-App-Id'] = "Token"
-// Configure API key authorization: X-App-Token
-const XAppToken = defaultClient.authentications["X-App-Token"];
-XAppToken.apiKey = "YOUR APP TOKEN";
-// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
-//X-App-Token.apiKeyPrefix['X-App-Token'] = "Token"
-// Configure OAuth2 access token for authorization: X-Voucherify-OAuth
-const XVoucherifyOAuth = defaultClient.authentications["X-Voucherify-OAuth"];
-XVoucherifyOAuth.accessToken = "";
-
-const api = new Voucherify.CampaignsApi(defaultClient);
-const callback = function (error, data, response) {
+## 🔒 Get your keys and address
+
+Get your Voucherify keys for valid authorization and setting the basePath (cluster) to match your server URL:
+1. In Voucherify dashboard, go to **Project settings**.
+2. In **Application information**, find your basePath (cluster) address. For shared clusters:
+   - Europe (default): `https://api.voucherify.io`
+   - United States: `https://us1.api.voucherify.io`
+   - Asia (Singapore): `https://as1.api.voucherify.io`
+3. Scroll down to **Application Keys** to grab your Application ID and Secret key.
+
+## 🚀 Run code
+
+Once installed, run:
+
+```typescript
+import * as Voucherify from "@voucherify/sdk";
+
+// Note: dotenv is an external library used for demonstration purposes only. It is not required.
+import dotenv from "dotenv";
+dotenv.config();
+
+const apiClient = Voucherify.ApiClient.instance;
+
+const HOST = process.env.VOUCHERIFY_HOST || "https://api.voucherify.io";
+const X_APP_ID = process.env.X_APP_ID;
+const X_APP_TOKEN = process.env.X_APP_TOKEN;
+
+apiClient.basePath = HOST;
+apiClient.authentications["X-App-Id"].apiKey = X_APP_ID;
+apiClient.authentications["X-App-Token"].apiKey = X_APP_TOKEN;
+
+const api = new Voucherify.CampaignsApi(apiClient);
+
+const options = {
+  filters: Voucherify.ParameterFiltersListCampaigns.constructFromObject({
+    junction: "and",
+    campaign_status:
+      Voucherify.ParameterFiltersListCampaignsCampaignStatus.constructFromObject(
+        {
+          conditions:
+            Voucherify.ParameterFiltersListCampaignsCampaignStatusConditions.constructFromObject(
+              {
+                $in: ["DONE"],
+              },
+            ),
+        },
+      ),
+  }),
+};
+
+const callback = function (
+  error: Error | null,
+  data?: Voucherify.CampaignsListResponseBody,
+  response?: any,
+) {
   if (error) {
     console.error(error);
   } else {
@@ -83,40 +148,158 @@ const callback = function (error, data, response) {
     );
   }
 };
-api.listCampaigns(undefined, callback);
 
+// Example with callback:
+api.listCampaigns(options, callback);
+
+// Example with promise:
+api.listCampaigns(options).then((response) => console.log(response));
 ```
 
-🛡️ This code does simple campaign list, so it won't affect Your Voucherify data.
+> [!NOTE]
+>
+> This code just lists campaigns, so it won't affect your Voucherify data.
+
+Once set up, check the following methods to give Voucherify a more interesting spin:
+- [Validations](docs/ValidationsApi.md#validateStackedDiscounts)
+- [Redemptions](docs/RedemptionsApi.md#redeemStackedDiscounts)
+- [Publications](docs/PublicationsApi.md#createPublication)
 
-🔒 Remember to fill in your Voucherify keys for valid authorization and set the basePath (cluster) to match your server URL.
+> [!TIP]
+>
+> Check the test implementation in the [Test folder](./test/).
 
-## 🐳 Running local tests with docker
+## 🐳 Run local tests with docker
 
+To run tests locally with docker:
 1. Copy `.env.example` to `.env` and fill in the values.
 2. Run `docker build -t js .` to build the image.
 3. Run `docker run --rm js` to run the tests and delete the container immediately after.
 
-## 🛠️ Contributing
+## 🛠️ Contribute
+
+Do you want to contribute?
+
+Read more about how to contribute to this SDK in the [Contributing guide](https://github.com/voucherifyio/voucherify-openapi/blob/master/GENERATING-SDKS.md) in the main repo.
+
+This SDK is auto-generated (except for tests), so changes made here will be overwritten by the generator.
+
+## 🏷️ Link tags
+
+[OpenAPI generated from tag](https://github.com/voucherifyio/voucherify-openapi/releases/tag/sdk-js-3.0.2).
+
+## 🔐 Authorization
+
+
+Authorization schemes defined for the API.
+### X-App-Id
+
+
+- **Type**: API key
+- **API key parameter name**: X-App-Id
+- **Location**: HTTP header
+
+### X-App-Token
+
+
+- **Type**: API key
+- **API key parameter name**: X-App-Token
+- **Location**: HTTP header
+
+### X-Client-Token
+
+
+- **Type**: API key
+- **API key parameter name**: X-Client-Token
+- **Location**: HTTP header
+
+### X-Client-Application-Id
+
+
+- **Type**: API key
+- **API key parameter name**: X-Client-Application-Id
+- **Location**: HTTP header
+
+### X-Management-Id
+
+
+- **Type**: API key
+- **API key parameter name**: X-Management-Id
+- **Location**: HTTP header
 
-Read more about how to Contribute to Voucherify JS SDK by visiting main repo [GENERATING-SDKS.md](https://github.com/voucherifyio/voucherify-openapi/blob/master/GENERATING-SDKS.md)
+### X-Management-Token
 
-Remember that this SDK is auto generated (except of the tests) so changes made here will be overwritten by generator.
 
-## Link tags
-[OpenAPI generated from tag](https://github.com/voucherifyio/voucherify-openapi/releases/tag/sdk-js-3.0.0)
+- **Type**: API key
+- **API key parameter name**: X-Management-Token
+- **Location**: HTTP header
+
+### X-Voucherify-OAuth
+
+
+- **Type**: OAuth
+- **Flow**: implicit
+- **Authorization URL**: https://api.voucherify.io/v1/oauth/token
+- **Scopes**: 
+  - api: Gives access to whole server-side API.
+  - vouchers: Gives access to all endpoints and methods starting with &#x60;v1/vouchers&#x60;.
+  - client_api: Gives access to whole client-side API.
+  - client_vouchers: Gives access to all endpoints and methods starting with &#x60;/client/v1/vouchers&#x60;.
+  - promotions: Gives access to all endpoints and methods starting with &#x60;/v1/promotions&#x60;.
+  - client_promotions: Gives access to all endpoints and methods starting with &#x60;/client/v1/promotions&#x60;
+  - campaigns: Gives access to all endpoints and methods starting with &#x60;v1/campaigns&#x60;.
+  - client_publish: Gives access to all endpoints and methods starting with &#x60;/client/v1/publish&#x60;.
+  - exports: Gives access to all endpoints and methods starting with &#x60;/v1/exports&#x60;.
+  - publications: Gives access to all endpoints and methods starting with &#x60;/v1/publications&#x60;.
+  - client_validate: Gives access to all endpoints and methods starting with &#x60;/client/v1/validate&#x60;.
+  - validations: Gives access to all endpoints and methods starting with &#x60;/v1/validations&#x60;.
+  - client_validations: Gives access to all endpoints and methods starting with &#x60;/client/v1/validations&#x60;.
+  - qualifications: Gives access to all endpoints and methods starting with &#x60;/v1/qualifications&#x60;.
+  - client_qualifications: Gives access to all endpoints and methods starting with &#x60;/client/v1/qualifications&#x60;.
+  - client_redeem: Gives access to all endpoints and methods starting with &#x60;/client/v1/redeem
+  - redemptions: Gives access to all endpoints and methods starting with &#x60;/v1/redemptions&#x60;.
+  - client_redemptions: Gives access to all endpoints and methods starting with &#x60;/client/v1/redemptions&#x60;
+  - customers: Gives access to all endpoints and methods starting with &#x60;/v1/customers&#x60;.
+  - client_customers: Gives access to all endpoints and methods starting with &#x60;/client/v1/customers&#x60;.
+  - orders: Gives access to all endpoints and methods starting with &#x60;/v1/orders&#x60;.
+  - products: Gives access to all endpoints and methods starting with &#x60;/v1/products&#x60;.
+  - skus: Gives access to all endpoints and methods starting with &#x60;/v1/SKUs&#x60;.
+  - validation-rules: Gives access to all endpoints and methods starting with &#x60;/v1/validation-rules&#x60;.
+  - validation-rules-assignments: Gives access to all endpoints and methods starting with &#x60;/v1/validation-rules-assignments
+  - segments: Gives access to all endpoints and methods starting with &#x60;/v1/segments&#x60;.
+  - events: Gives access to all endpoints and methods starting with &#x60;/v1/events&#x60;.
+  - client_events: Gives access to all endpoints and methods starting with &#x60;client/v1/events&#x60;.
+  - rewards: Gives access to all endpoints and methods starting with &#x60;/v1/rewards&#x60;.
+  - assets: Gives access to all endpoints and methods starting with &#x60;/v1/assets&#x60;.
+  - task-results: Gives access to all endpoints and methods starting with &#x60;/v1/task-results&#x60;.
+  - loyalties: Gives access to all endpoints and methods starting with &#x60;/v1/loyalties&#x60;.
+  - client_consents: Gives access to all endpoints and methods starting with &#x60;client/v1/consents&#x60;.
+  - consents: Gives access to all endpoints and methods starting with &#x60;/v1/consents&#x60;.
+  - async-actions: Gives access to all endpoints and methods starting with &#x60;/v1/async-actions&#x60;.
+  - product-collections: Gives access to all endpoints and methods starting with &#x60;/v1/product-collections&#x60;.
+  - categories: Gives access to all endpoints and methods starting with &#x60;/v1/categories&#x60;.
+  - metadata-schemas: Gives access to all endpoints and methods starting with &#x60;/v1/metadata-schemas&#x60;.
+  - locations: Gives access to all endpoints and methods starting with &#x60;/v1/locations&#x60;.
+  - referrals: Gives access to all endpoints and methods starting with &#x60;/v1/referrals&#x60;.
+  - trash-bin: Gives access to all endpoints and methods starting with &#x60;/v1/trash-bin&#x60;.
+  - templates: Gives access to all endpoints and methods starting with &#x60;/v1/templates&#x60;.
+
 
 ## 📅 Changelog
 
-- **2024-09-05** - `3.0.0` - The new version of the SDK includes coverage for all the most commonly used Voucherify endpoints and supports typed models.
+- **2025-12-31** - `3.0.2`:
+    - Added the `AUTO_UPDATE` enum value to the `type` property in the `ProductCollectionsCreateRequestBody` model.
+    - Added support for the new `filters` query parameter in the `listVouchers` method of `VouchersApi` (GET /v1/vouchers).
+- **2025-11-24** - `3.0.1` - Introduced native TypeScript type definitions generated from JSDoc, enabling automatic type inference and IDE autocompletion.
+- **2025-11-05** - `3.0.0` - The new version of the SDK includes coverage for all the most commonly used Voucherify endpoints and supports typed models.
 
-*Previous versions of the SDK are no longer supported, and we highly recommend upgrading to version 3.0.0, which is now designated as Long-Term Support (LTS).*
+*Previous versions of the SDK are no longer supported. We highly recommend upgrading to version 3.0.0 or newer, as it is now designated as Long-Term Support (LTS).*
 
-*Changelog for previous versions could be found in the [DEPRECATED_CHANGELOG.md file](./DEPRECATED_CHANGELOG.md)*
+*Changelog for previous versions is in the [DEPRECATED_CHANGELOG.md file](./DEPRECATED_CHANGELOG.md)*
 
-## Documentation for API Endpoints
+## 🌐 Documentation of API endpoints
 
-All URIs are relative to *https://{cluster}.voucherify.io*
+All URIs are relative to *https://{cluster}.api.voucherify.io*
 
 Class | Method | HTTP request | Description
 ------------ | ------------- | ------------- | -------------
@@ -366,7 +549,7 @@ Class | Method | HTTP request | Description
 *Voucherify.VouchersApi* | [**updateVouchersMetadataInBulk**](docs/VouchersApi.md#updateVouchersMetadataInBulk) | **POST** /v1/vouchers/metadata/async | Update Vouchers&#39; Metadata in Bulk
 
 
-## Documentation for Models
+## 📚 Documentation of models
 
  - [Voucherify.AccessSettings](docs/AccessSettings.md)
  - [Voucherify.AccessSettingsAssign](docs/AccessSettingsAssign.md)
@@ -1729,100 +1912,3 @@ Class | Method | HTTP request | Description
  - [Voucherify.VouchersUpdateResponseBodyPublish](docs/VouchersUpdateResponseBodyPublish.md)
  - [Voucherify.VouchersUpdateResponseBodyRedemption](docs/VouchersUpdateResponseBodyRedemption.md)
 
-
-## Documentation for Authorization
-
-
-Authentication schemes defined for the API:
-### X-App-Id
-
-
-- **Type**: API key
-- **API key parameter name**: X-App-Id
-- **Location**: HTTP header
-
-### X-App-Token
-
-
-- **Type**: API key
-- **API key parameter name**: X-App-Token
-- **Location**: HTTP header
-
-### X-Client-Token
-
-
-- **Type**: API key
-- **API key parameter name**: X-Client-Token
-- **Location**: HTTP header
-
-### X-Client-Application-Id
-
-
-- **Type**: API key
-- **API key parameter name**: X-Client-Application-Id
-- **Location**: HTTP header
-
-### X-Management-Id
-
-
-- **Type**: API key
-- **API key parameter name**: X-Management-Id
-- **Location**: HTTP header
-
-### X-Management-Token
-
-
-- **Type**: API key
-- **API key parameter name**: X-Management-Token
-- **Location**: HTTP header
-
-### X-Voucherify-OAuth
-
-
-- **Type**: OAuth
-- **Flow**: implicit
-- **Authorization URL**: https://api.voucherify.io/v1/oauth/token
-- **Scopes**: 
-  - api: Gives access to whole server-side API.
-  - vouchers: Gives access to all endpoints and methods starting with &#x60;v1/vouchers&#x60;.
-  - client_api: Gives access to whole client-side API.
-  - client_vouchers: Gives access to all endpoints and methods starting with &#x60;/client/v1/vouchers&#x60;.
-  - promotions: Gives access to all endpoints and methods starting with &#x60;/v1/promotions&#x60;.
-  - client_promotions: Gives access to all endpoints and methods starting with &#x60;/client/v1/promotions&#x60;
-  - campaigns: Gives access to all endpoints and methods starting with &#x60;v1/campaigns&#x60;.
-  - client_publish: Gives access to all endpoints and methods starting with &#x60;/client/v1/publish&#x60;.
-  - exports: Gives access to all endpoints and methods starting with &#x60;/v1/exports&#x60;.
-  - publications: Gives access to all endpoints and methods starting with &#x60;/v1/publications&#x60;.
-  - client_validate: Gives access to all endpoints and methods starting with &#x60;/client/v1/validate&#x60;.
-  - validations: Gives access to all endpoints and methods starting with &#x60;/v1/validations&#x60;.
-  - client_validations: Gives access to all endpoints and methods starting with &#x60;/client/v1/validations&#x60;.
-  - qualifications: Gives access to all endpoints and methods starting with &#x60;/v1/qualifications&#x60;.
-  - client_qualifications: Gives access to all endpoints and methods starting with &#x60;/client/v1/qualifications&#x60;.
-  - client_redeem: Gives access to all endpoints and methods starting with &#x60;/client/v1/redeem
-  - redemptions: Gives access to all endpoints and methods starting with &#x60;/v1/redemptions&#x60;.
-  - client_redemptions: Gives access to all endpoints and methods starting with &#x60;/client/v1/redemptions&#x60;
-  - customers: Gives access to all endpoints and methods starting with &#x60;/v1/customers&#x60;.
-  - client_customers: Gives access to all endpoints and methods starting with &#x60;/client/v1/customers&#x60;.
-  - orders: Gives access to all endpoints and methods starting with &#x60;/v1/orders&#x60;.
-  - products: Gives access to all endpoints and methods starting with &#x60;/v1/products&#x60;.
-  - skus: Gives access to all endpoints and methods starting with &#x60;/v1/SKUs&#x60;.
-  - validation-rules: Gives access to all endpoints and methods starting with &#x60;/v1/validation-rules&#x60;.
-  - validation-rules-assignments: Gives access to all endpoints and methods starting with &#x60;/v1/validation-rules-assignments
-  - segments: Gives access to all endpoints and methods starting with &#x60;/v1/segments&#x60;.
-  - events: Gives access to all endpoints and methods starting with &#x60;/v1/events&#x60;.
-  - client_events: Gives access to all endpoints and methods starting with &#x60;client/v1/events&#x60;.
-  - rewards: Gives access to all endpoints and methods starting with &#x60;/v1/rewards&#x60;.
-  - assets: Gives access to all endpoints and methods starting with &#x60;/v1/assets&#x60;.
-  - task-results: Gives access to all endpoints and methods starting with &#x60;/v1/task-results&#x60;.
-  - loyalties: Gives access to all endpoints and methods starting with &#x60;/v1/loyalties&#x60;.
-  - client_consents: Gives access to all endpoints and methods starting with &#x60;client/v1/consents&#x60;.
-  - consents: Gives access to all endpoints and methods starting with &#x60;/v1/consents&#x60;.
-  - async-actions: Gives access to all endpoints and methods starting with &#x60;/v1/async-actions&#x60;.
-  - product-collections: Gives access to all endpoints and methods starting with &#x60;/v1/product-collections&#x60;.
-  - categories: Gives access to all endpoints and methods starting with &#x60;/v1/categories&#x60;.
-  - metadata-schemas: Gives access to all endpoints and methods starting with &#x60;/v1/metadata-schemas&#x60;.
-  - locations: Gives access to all endpoints and methods starting with &#x60;/v1/locations&#x60;.
-  - referrals: Gives access to all endpoints and methods starting with &#x60;/v1/referrals&#x60;.
-  - trash-bin: Gives access to all endpoints and methods starting with &#x60;/v1/trash-bin&#x60;.
-  - templates: Gives access to all endpoints and methods starting with &#x60;/v1/templates&#x60;.
-