Pz/test2

.env.example

@@ -0,0 +1,9 @@
+README_IO_AUTH=enter_your_readme_key_after_the_equals_sign
+
+# REQUIRED FOR SDKS TESTS
+VOUCHERIFY_HOST=https://api.voucherify.io
+X_APP_ID=
+X_APP_TOKEN=
+X_MANAGEMENT_ID=
+X_MANAGEMENT_TOKEN=
+PROJECT_ID=

.gitignore

@@ -0,0 +1,16 @@
+node_modules
+scripts/output/*.md
+.env
+.DS_Store
+.idea/*
+/reference/.stoplight/
+/tmp/
+openapitools.json
+sdk-tests/java/target
+/sdk-tests/java/.idea/*
+/sdk-tests/php/vendor/
+/sdk-tests/php/src/
+/sdk-tests/php/tests/
+/sdk-tests/php/docs/
+/docs/webhooks/
+/logs/

.gitmodules

@@ -0,0 +1,15 @@
+[submodule "sdks/ruby"]
+	path = sdks/ruby
+	url = https://github.com/voucherifyio/voucherify-ruby-sdk
+[submodule "sdks/java"]
+	path = sdks/java
+	url = https://github.com/voucherifyio/voucherify-java-sdk
+[submodule "sdks/python"]
+	path = sdks/python
+	url = https://github.com/voucherifyio/voucherify-python-sdk
+[submodule "sdks/php"]
+	path = sdks/php
+	url = https://github.com/voucherifyio/voucherify-php-sdk
+[submodule "sdks/dotnet"]
+	path = sdks/dotnet
+	url = https://github.com/voucherifyio/voucherify-dotNET-sdk

.java-version

@@ -0,0 +1 @@
+openjdk64-24.0.1

19-how-does-the-distribution-manager-work.mdx

@@ -0,0 +1,4 @@
+---
+url: "https://support.voucherify.io/article/19-how-does-the-distribution-manager-work"
+---
+

405-integration-catalog.mdx

@@ -0,0 +1,4 @@
+---
+url: "https://support.voucherify.io/category/405-integration-catalog?sort=name"
+---
+

48-referral-program-basics.mdx

@@ -0,0 +1,4 @@
+---
+url: "https://support.voucherify.io/article/48-referral-program-basics"
+---
+

491-getting-started-with-loyalty-programs.mdx

@@ -0,0 +1,4 @@
+---
+url: "https://support.voucherify.io/article/491-getting-started-with-loyalty-programs"
+---
+

538-sandbox.mdx

@@ -0,0 +1,4 @@
+---
+url: "https://support.voucherify.io/article/538-sandbox"
+---
+

NEW-SDKS.md

@@ -0,0 +1,95 @@
+# NEW SDKs FROM THE OPENAPI FILE
+
+## Introduction
+
+Sometimes, we need to generate an entirely new SDK from the OpenAPI file. This guide covers the steps required to create a new SDK.
+
+If there are missing steps or any other content here, feel free to update this guide.
+
+## Requirements
+
+See [GENERATING SDKS](/GENERATING-SDKS.md).
+
+## How to generate an SDK
+
+1. Check the latest version of the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator). Download the `cli-X.X.X.jar` file if it is not already present in the `./openapi-generator-jar` folder for the required version.
+    1. Go to the repository and read `README.md`. You may need to generate the CLI yourself. Instructions should be in the README file. Java is required. The needed file is `openapi-generator-cli-*****.jar`. Alternatively, you can find a prebuilt [SNAPSHOT](https://oss.sonatype.org/content/repositories/snapshots/org/openapitools/openapi-generator-cli/7.12.0-SNAPSHOT/).
+    2. Add the new `openapi-generator-cli-*****.jar` to the `./openapi-generator-jar` folder.
+    3. Go to the repository and find the Mustache template. It should be in `modules/openapi-generator/src/main/resources/{language}`.
+    4. Copy the Mustache template to `./mustache-templates`.
+
+2. Open [`./scripts/prepare-open-api-for-sdk/index.ts`](./scripts/prepare-open-api-for-sdk/index.ts) and add support for the new SDK, following the structure of the previous SDKs.
+    1. This step may require special care since some SDKs have specific limitations. For example:
+        - **Python** does not allow multiple response statuses for a single path, it is needed to merge them using the `use2XX` option.
+        - Some SDKs can't have both `additionalProperties` and regular properties simultaneously, so the `simplifyAllObjectsThatHaveAdditionalProperties` option is needed.
+        - In some cases, OpenAPI must be structured in a specific way, such as using the `putNotObjectSchemasIntoObjectSchemas` option to ensure enums are correctly placed inside object models.
+        - There is no universal solution for these issues. Start without additional options, then test the generated SDK and make sure everything works as expected.
+        - A new SDK should contain all breaking changes, so provide `breakingChangesVersion` option with the highest number (+1 if the highest number already has all known breaking changes see `if (languageOptions.breakingChangesVersion <= {highestNumber}) {`)
+    2. The new SDK should include all breaking changes.
+
+3. Open [`./scripts/helpers/get-take-list.ts`](./scripts/helpers/get-take-list.ts) and add support for the new SDK. All non-deprecated paths should be included.
+
+4. Open [`./scripts/generate-endpoints-coverage-doc.ts`](./scripts/generate-endpoints-coverage-doc.ts) and add support for the new SDK.
+
+5. Generate the OpenAPI file for the new SDK. It should be located in `./reference/readonly-sdks/{language}/OpenAPI.json`.
+
+6. In `package.json`, create a new script to generate the SDK. It should look like this:
+   ```json
+   "generate-sdk-{language}": "npm run generate-endpoints-coverage-doc -- --generateFor={language}; rm -r ./sdks/{language}/{sdk_generated_file_folder}; npm run prepare-open-api-for-sdk -- --language={language}; java -jar openapi-generator-jar/openapi-generator-cli-X.X.X.jar generate -i ./reference/readonly-sdks/{language}/OpenAPI.json -g {language} -o ./sdks/{language} -t ./mustache-templates/{language} --additional-properties={check_documentation}"
+   ```  
+    1. `{language}` should be replaced with the target language, e.g., `csharp` or `php-nextgen`.
+    2. To determine correct `additional-properties`, visit [OpenAPI Generator Documentation](https://openapi-generator.tech/docs/generators) and select your language.
+
+7. Add your script to `generate-sdks` in `package.json`.
+
+8. Generate the SDK with your script.
+    - Add submodule, it can be for example `git submodule add https://github.com/voucherifyio/voucherify-{language}-sdk sdks/{language}`.
+    - It's recommended to use an old repository. If a repository doesn't exist, create a new one.
+
+9.  **Recommended:** Remove auto-generated SDK tests.
+    - Add a command to your `generate-sdk-{language}` script to remove the tests automatically.
+    - This is recommended since it was found they had limited use.
+
+10. Modify the Mustache templates:
+    - Remove all safety guards that throw errors due to model mismatches.
+    - It is best not to enforce these checks, as new API properties are frequently added, and such safety guards could break the SDK.
+    - Look for error-throwing conditions in the generated SDK language and remove them.
+
+11. Create tests that ensure:
+    1. The test suite loads the `./env` file. Add `./env.example`, `./env` must be added to `.gitigniore`. The file must contain:
+       ```plaintext
+       VOUCHERIFY_HOST=https://api.voucherify.io
+       X_APP_ID=
+       X_APP_TOKEN=
+       X_MANAGEMENT_ID=
+       X_MANAGEMENT_TOKEN=
+       ```  
+    2. Using `X_APP_ID` and `X_APP_TOKEN`:
+        - Create a simple campaign and a customer.
+        - Retrieve a voucher from a campaign.
+        - Import CSV with vouchers; make sure the upload was successful.
+        - Query qualifications.
+        - Perform validation and redemption successfully.
+        - Compare at least a few response parameters using `expect()`.
+    3. Using `X_MANAGEMENT_ID` and `X_MANAGEMENT_TOKEN`:
+        - Query projects.
+        - List metadata schemas.
+        - Update a metadata schema successfully.
+        - Ensure some `expect()` checks are included.
+    4. Using `X_APP_ID` and `X_APP_TOKEN`:
+        - Create an OAuth token with the `api` scope.
+        - Repeat the steps from point 2.
+    5. **Ensure that an object containing both regular properties and additional properties in the same model is tested.**
+        - This is critical to verify that complex objects are correctly generated.
+        - If issues arise, update the SDK generation options accordingly.
+
+12. Once the tests are ready:
+    - Prepare a Dockerfile that installs the SDK (if necessary) and runs the tests.
+    - You can find examples in existing SDKs: `./sdks/{language}/Dockerfile`.
+    - Add a script in `package.json` under `test-{language}-sdk` and update the `test-sdks` script.
+
+13. Update the SDK README.
+    - This will likely involve modifying `./mustache-templates/{language}/README.mustache`.
+    - Ensure it is useful and structured similarly to other SDKs.
+
+14. Research how to publish the SDK to the appropriate package manager (e.g., Maven, npm) based on its language.

README.md

@@ -1,44 +1,21 @@
-# Mintlify Starter Kit
+# Voucherify's OpenAPI Specification and SDK
 
-Use the starter kit to get your docs deployed and ready to customize.
+[![JAVA SDK](https://img.shields.io/badge/JAVA-SDK-FF0000?logo=openjdk&logoColor=red)](https://github.com/voucherifyio/sdk-java-openapi-based)
+[![PHP SDK](https://img.shields.io/badge/PHP-SDK-777BB4?logo=php&logoColor=white)](https://github.com/voucherifyio/sdk-php-openapi-based)
+[![PYTHON SDK](https://img.shields.io/badge/PYTHON-SDK-58ad09?logo=python&logoColor=green)](https://github.com/voucherifyio/sdk-python-openapi-based)
+[![RUBY SDK](https://img.shields.io/badge/RUBY-SDK-c71628?logo=ruby&logoColor=c71628)](https://github.com/voucherifyio/sdk-ruby-openapi-based)
 
-Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
+This repository contains OpenAPI specification for Voucherify's API.
 
-- Guide pages
-- Navigation
-- Customizations
-- API reference pages
-- Use of popular components
+ - **Version supported**: `3.0.1`
+ - **Spec location**: [/production/readOnly-openAPI.json](/production/readOnly-openAPI.json)
+ - **Changelog**: `Changelog.md`
+ - **Status**: _Released_
 
-**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
+This OpenAPI specification is live. 
 
-## Development
-
-Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
-
-```
-npm i -g mint
-```
-
-Run the following command at the root of your documentation, where your `docs.json` is located:
-
-```
-mint dev
-```
-
-View your local preview at `http://localhost:3000`.
-
-## Publishing changes
-
-Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
-
-## Need help?
-
-### Troubleshooting
-
-- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
-- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
-
-### Resources
-- [Mintlify documentation](https://mintlify.com/docs)
-- [Mintlify community](https://mintlify.com/community)
+Please refer to the following guides:
+- [Guides](https://docs.voucherify.io/docs)
+- [Recipes](https://docs.voucherify.io/recipes)
+- [API Reference](https://docs.voucherify.io/reference/)
+- [Support Documentation](https://support.voucherify.io/)

SDKS.md

@@ -0,0 +1,164 @@
+# GENERATING SDKs FROM OPEN API FILE
+
+## Introduction
+
+We use [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) with version 7.0.1, 7.1.0, 7.8.0 and 7.12.0 (depending on the SDK)
+
+We use jar file generators located in `./openapi-generator-jar` to generate SDKs for different languages.
+
+The template (mustache) files are located in `./mustache-templates` directory. 
+They are slightly modified from the original ones for our needs.
+
+## Requirements
+
+- Node.js ^22 and npm
+- docker (optional)
+- java runtime v18 or higher
+
+## How to generate an SDK
+
+1. Run `npm install`, if you have not already installed.
+2. Run `npm run generate-sdk-ruby`/`generate-sdk-python`/`generate-sdk-java`/`generate-sdk-php`/`generate-sdk-dotnet`.
+
+SDK will be generated in `./sdks` directory in the respective language folder.
+
+## Command explanation
+
+### `build-update-md-tables-from-openapi`
+
+Creates and updates docs in `./docs/reference-docs` directory.
+
+### `remove-stoplight-tags-from-openapi`
+
+Spotlight is GUI software for editing OpenAPI files. Each usage added some tags to an OpenAPI file. This command removes them.
+
+### `prepare-open-api-for-sdk`
+
+Scripts in the basic form are not ready for generating SDKs without errors or bugs. This command performs actions which are mostly language-specific.
+  - (all) removing unsupported endpoints (deprecated or those that wasn't refactored to the newest versions of the API)
+  - (all) removing not used schemas and parameters 
+  - (all) removing `additionalProperties` from schemas
+  - (java / python) removing `required` property from schema parameters that is assigned as `nullable`
+  - (java) merging multiple response schemas with 2xx status code into one schema
+  - (php) merging `oneOf` schemas into one schema
+  - (php) associating each element into object
+
+### `create-clean-project`
+
+Run `build-update-md-tables-from-openapi` command to upload the OpenAPI file to the ReadMe server.
+
+### `fix-schemas-with-refs
+
+Fixes `oneOf` schemas with `$ref`.
+
+### `fix-schemas-properties-with-single-enum`
+
+Adds default values to schemas with a single enum.
+
+### `readme-upload-missing-images`
+
+Uploads images to the ReadMe server.
+
+### `count-important-statistics-about-openapi`
+
+Counts occurrences and statistics which are important for OpenAPI correctness.
+
+### `build-production-openapi`
+
+Creates an OpenAPI snapshot file which is uploaded to the ReadMe server.
+
+### `fix-zero-level-schemas`
+
+Generates an OpenAPI file with correct zero-level schemas for requests and responses consistent with the arrangements from [CONTRIBUTING.md](CONTRIBUTING.md#naming-convention).
+
+### `generate-endpoints-coverage-docs`
+
+Generates a readme file with endpoints coverage.
+
+### `generate-sdk-xxx`
+
+Generates an SDK in a given language.
+
+### `generate-sdks`
+
+Generates all SDKs at the same time.
+
+## `test
+
+Checks if the OpenAPI schemas haven't changed after scripts refactoring.
+
+## Creating changes 
+
+1. Init all submodules `git submodule update --init --recursive`.
+2. Create a new branch: `git checkout -b MY_BRANCH_NAME`
+3. Add changes in accordance with [CONTRIBUTING.md](./CONTRIBUTING.md).
+4. [Generate SDKs](#how-to-generate-sdk).
+5. Create new ones for your changes and [ensure everything runs without errors](#running-tests).
+6. Commit all changes to the main repo and submodules.
+7. Push your branch and create a [pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) against the `main` branch.
+8. When the changes are merged, [publish the new version to remote repositories](#publishing-for-remote-repositories-).
+
+## Running tests
+
+The easiest way for running tests is to use the `docker-compose` file.
+1. Ensure that you have installed `docker`.
+2. Ensure that you have the init submodules with `git submodule update --init --recursive`.
+3. Make sure you filled up `./env` file in root directory and `./scripts/copy-env-to-sdks.sh` have been launched.
+4. Run `npm run test-sdks` or `npm run test-python-sdk/test-php-sdk/test-java-sdk/test-ruby-sdk/test-dotnet-sdk`
+
+To run SDKs separately or on your local machine without docker, go to the SDK directory and read the `README.md` file.
+
+**Running tests will affect your Voucherify project data. Run tests only on development projects!**
+
+## Uploading new versions
+
+Manual steps checklist:
+- [ ] Ensure that all SDKs were generated without errors.
+- [ ] Ensure new tests were created for changes.
+- [ ] Ensure that all SDKs tests passed.
+- [ ] Make sure no breaking changes have been introduced - only as a last resort can such changes be added (read section "Releasing major version")
+- [ ] Commit all generated changes to the submodules and main module.
+- [ ] Publish the new version of the SDKs to repositories manager.
+
+### Versioning 
+
+- **patch** - backward compatible changes - bug fixes, small changes, refactoring.
+- **minor** - backward compatible changes - new endpoints or properties.
+- **major** - breaking changes - new schemas, naming changes, removing endpoints or properties, changes in the mustache logic.
+
+### Version Update Process
+
+When updating the version number from X.Y.Z to U.I.O:
+
+1. Search and replace all version number occurrences across:
+    - Main repository
+    - All language-specific SDK in `sdks/**language*` directories
+
+2. **Important Exception:**
+    - Skip version number updates in `sdks/**language**/README.md` files where X.Y.Z appears in changelog entries
+    - These changelog entries should be preserved for historical documentation
+
+3. **Search Pattern:**
+    - Look for exact matches of the previous version number (X.Y.Z)
+    - Replace with new version number (U.I.O)
+
+Note: This process ensures version consistency across the codebase while maintaining changelog history.
+
+#### Breaking changes
+
+The following changes to the `OpenAPI.json` file consistent breaking changes:
+- Adding a new query parameter.
+- Deleting anything: a query property, a schema, property schema, etc.
+- Changing the order of query parameters.
+- When an object is replaced with a `$ref`.
+- Deleting an element from an `enum`.
+- Adding an `enum` if, until now, the type was `string`.
+- Adding `format` or its change in a schema which has `"type": "string"`.
+- Adding a `default` (**most likely**).
+- Adding a new `enum` value if the existing values have the same prefix.
+
+To avoid breaking changes, fix them in the [`index.ts` file](./scripts/prepare-open-api-for-sdk/index.ts).
+
+#### Releasing major version
+
+Before releasing new major version please go to [`index.ts` file](./scripts/prepare-open-api-for-sdk/index.ts) and update `breakingChangesVersion` to make sure that all breaking changes will be applied at the same time.