> **This repository is auto-generated by the [Revenexx SDK Generator](https://github.com/revenexx/sdk-generator). Do not submit changes directly — they will be overwritten on the next generation run.**

# Revenexx Web SDK

![License](https://img.shields.io/github/license/revenexx-sdks/web.svg?style=flat-square)
![Version](https://img.shields.io/badge/api%20version-1.0.0-blue.svg?style=flat-square)
[![Build Status](https://img.shields.io/github/actions/workflow/status/revenexx/sdk-generator/tests.yml?style=flat-square)](https://github.com/revenexx/sdk-generator/actions)
[![Twitter Account](https://img.shields.io/twitter/follow/revenexx?color=00acee&label=twitter&style=flat-square)](https://twitter.com/revenexx)

Revenexx is a backend platform for building scalable web and mobile applications. This SDK gives you direct access to the Revenexx APIs from your browser or server.

![Revenexx Web](https://revenexx.com/images/logo.svg)

## Installation

### NPM

Install the package from the [npm registry](https://www.npmjs.com/package/@revenexx/sdk):

```bash
npm install @revenexx/sdk --save
```

If you're using a bundler (like [Rollup](https://rollupjs.org/) or [webpack](https://webpack.js.org/)), you can import the Revenexx Web module when you need it:

```js
import { Client, Greetings } from "@revenexx/sdk";
```


## Getting Started

### Init your SDK

Initialize your SDK with your Revenexx API endpoint, your tenant slug and your credentials. The tenant slug is sent as the `X-Revenexx-Tenant` header on every request. The client supports two authentication methods:

- **API key** — a gateway-managed scoped key (`rvxk_…`), set via `setApiKeyAuth()`. Intended for server-side or trusted environments; never embed an API key in code shipped to the browser.
- **Bearer token** — a Zitadel-issued JWT for interactive callers, set via `setBearerAuth()`. The value is sent as the `Authorization` header verbatim, so include the `Bearer ` prefix.

```js
import { Client } from "@revenexx/sdk";

const client = new Client();

client
    .setEndpoint('https://api.revenexx.com') // Your Revenexx API endpoint
    .setTenant('<TENANT_SLUG>')              // Your tenant slug
    .setApiKeyAuth('rvxk_...')               // Your scoped API key
;
```

Or, with a user JWT:

```js
client
    .setEndpoint('https://api.revenexx.com')
    .setTenant('<TENANT_SLUG>')
    .setBearerAuth(`Bearer ${jwt}`)
;
```

### Make Your First Request

Once your client is set up, instantiate any of the Revenexx services with it and send a request. All service methods accept a single params object and return a promise. Full documentation for every service method can be found in the [API References](https://revenexx.com/docs).

```js
import { Client, Greetings } from "@revenexx/sdk";

const greetings = new Greetings(client);

await greetings.greetingsCreate({
    name: 'World',
    locale: 'en-US',
});
```

### Full Example

```js
import { Client, Greetings } from "@revenexx/sdk";

const client = new Client();

client
    .setEndpoint('https://api.revenexx.com')
    .setTenant('<TENANT_SLUG>')
    .setApiKeyAuth('rvxk_...')
;

const greetings = new Greetings(client);

await greetings.greetingsCreate({
    name: 'World',
    locale: 'en-US',
});

const greeting = await greetings.greetingsGet({ id: '<GREETING_ID>' });
console.log(greeting.message);
```

### Type Safety with Models

The SDK ships with full TypeScript definitions. Response types live in the `Models` namespace, and every service method is typed against them — including nullable fields, which are typed as `| null`.

```typescript
import { Client, Customers, type Models } from "@revenexx/sdk";

const customers = new Customers(client);

const address: Models.Address = await customers.customersAddressesGet({
    id: '<ADDRESS_ID>',
});

console.log(address.street, address.city);
console.log(address.company); // string | null
```

### Error Handling

The Revenexx Web SDK raises a `RevenexxException` object with `message`, `code` and `response` properties. You can handle any errors by catching the exception and present the `message` to the user or handle it yourself based on the provided error information.

```javascript
import { RevenexxException } from "@revenexx/sdk";

try {
    const greeting = await greetings.greetingsGet({ id: '<GREETING_ID>' });
    console.log(greeting);
} catch (error) {
    if (error instanceof RevenexxException) {
        console.error(error.code, error.message);
    }
}
```

### Learn more

You can use the following resources to learn more and get help

- 📜 [Revenexx Docs](https://revenexx.com/docs)
- 💬 [Discord Community](https://revenexx.com/discord)

## Contribution

This library is auto-generated by the [Revenexx SDK Generator](https://github.com/revenexx/sdk-generator). To learn more about how you can contribute, please check the [contribution guide](https://github.com/revenexx/sdk-generator/blob/main/CONTRIBUTING.md) before sending a pull-request.

## License

Please see the [ license]() file for more information.