Get Started

OneEntry Platform SDK is an SDK that provides an easy way to interact with the OneEntry Platform API.

🚀 Quick Start

Get up and running with OneEntry in 3 simple steps:

1️⃣ Install the package

  npm install oneentry

2️⃣ Initialize the SDK

  import { defineOneEntry } from 'oneentry';

  const api = defineOneEntry('your-project-url', {
    token: 'your-api-token'
  });

3️⃣ Start using the API

  // Fetch products 
  const products = await api.Products.getProducts({ limit: 10 });

  // Get user profile
  const user = await api.Users.getUser();

  // Submit a form
  const formData = await api.FormData.postFormsData('contact-form', {
    name: 'John Doe',
    email: 'john@example.com'
  });

🎉 That's it! You're ready to build amazing applications with OneEntry.

✨ Key Features

🔐

Secure Authentication

Built-in token management and OAuth support

🌍

Multi-language

i18n support with automatic language detection

📝

TypeScript

Full type definitions for better DX

⚡

Lightweight

Optimized bundle size for production

🔌

Modular Architecture

24 specialized modules for all your needs

🛡️

Error Handling

Custom error handlers and shell mode

🌐 Resources

🌍

Official Website

Learn more about OneEntry Platform

🚀

Sign Up

Create your free account

💻

Npmjs

Download SDK

📖 Detailed Usage

All Available Modules

Import and destructure all modules you need:


import { defineOneEntry } from 'oneentry'

const config = {
  token: 'your-app-token',
}
const {
  Admins,
  AttributesSets,
  AuthProvider,
  Blocks,
  Events,
  FileUploading,
  Forms,
  FormData,
  GeneralTypes,
  IntegrationCollections,
  Locales,
  Menus,
  Orders,
  Pages,
  Payments,
  ProductStatuses,
  Products,
  Settings,
  System,
  Templates,
  TemplatePreviews,
  Users,
  WS
} = defineOneEntry('your-url', config);

const config = {
  token: 'your-app-token',
};

const api = defineOneEntry('your-url', config);

Config

The second parameter of the constructor takes the 'config'. It contains the following values:

'token' - Set the token key if your project secure "Security API Token". If you are using certificate protection, do not pass this variable. You can read more about the security of your project here.
'langCode' - Set the "langCode" to set the default language. By specifying this parameter once, you don't have to pass the langCode to the methods ONEENTRY API. If you have not passed the default language, it will be set "en_US".
'traficLimit' - Some methods use more than one request to the OneEntry so that the data you receive is complete and easy to work with. Pass the value "true" for this parameter to save traffic and decide for yourself what data you need. The default value "false".
'auth' - An object with authorization settings. By default, the SDK is configured to work with tokens inside the user's session and does not require any additional work from you. At the same time, the SDK does not store the session state between sessions. If you are satisfied with such settings, do not pass the variable 'auth' at all.

The 'auth' contains the following settings:

'refreshToken' - The user's refresh token. Transfer it here from the repository to restore the user's session during initialization.
'saveFunction' - A function that works with the update refresh token. If you want to store the token between sessions, for example in local storage, pass a function here that does this. The function must accept a parameter to which the string with the token will be passed.
'customAuth' - If you want to configure authorization and work with tokens yourself, set this flag to true. If you want to use the sdk settings, set it to false or do not transfer it at all.
'providerMarker' - The marker for the auth provider. Default: 'email'. An example of a configuration with token protection and automatic authentication that stores state between sessions

const tokenFunction = (token) => {
  localStorage.setItem('refreshToken', token);
};

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  token: 'my-token',
  langCode: 'en_US',
  auth: {
    refreshToken: localStorage.getItem('refreshToken'),
    saveFunction: tokenFunction,
    providerMarker: 'email'
  },
});

An example of a configuration that is protected with a certificate allows you to configure the authorization system yourself and saves data on requests.

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  langCode: 'en_US',
  traficLimit: true,
  auth: {
    customAuth: true,
    refreshToken: localStorage.getItem('refreshToken'),
    providerMarker: 'email'
  },
});

If you have chosen to configure tokens yourself, you can pass the token to the method as follows. The intermediate method allows you to pass an access token to the request. Then call the required method. This method (setAccessToken) should not be called if the method does not require user authorization.

const user = api.Users.setAccessToken('my.access.token').getUser();

If you chose token protection to ensure connection security, just pass your token to the function as an optional parameter.

You can get a token as follows

Log in to your personal account
Go to the "Projects" tab and select a project
Go to the "Access" tab
Set the switch to "Security API Token"
Log in to the project, go to the settings section and open the token tab
Get and copy the token of your project

You can also connect a tls certificate to protect your project. In this case, do not pass the "token" at all. When using the certificate, set up a proxy in your project. Pass an empty string as an url parameter. Learn more about mtls certificate

const saveTokenFromLocalStorage = (token) => {
  localStorage.setItem('refreshToken', token);
};

const api = defineOneEntry('your-url', {
  token: 'my-token',
  langCode: 'my-langCode',
  auth: {
    customAuth: false,
    userToken: 'rerfesh.token',
    saveFunction: saveTokenFromLocalStorage,
    providerMarker: 'email'
  },
});

API Response Validation

OneEntry SDK includes optional validation of API responses using Zod, a TypeScript-first schema validation library. This feature helps ensure data integrity and type safety when working with API responses.

Features

Optional: Validation is disabled by default and can be enabled per configuration
Type-safe: Uses Zod schemas that align with TypeScript interfaces
Two modes: Soft mode (logs errors) and strict mode (returns errors)
Zero runtime overhead when disabled: No performance impact if validation is turned off

Configuration

Enable validation by adding the validation property to your SDK configuration:

import { defineOneEntry } from 'oneentry'

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,        // Enable validation (default: false)
    strictMode: false,    // Strict mode (default: false)
    logErrors: true,      // Log validation errors (default: true)
  }
})

Configuration Options

Option	Type	Default	Description
`enabled`	`boolean`	`false`	Enable/disable response validation
`strictMode`	`boolean`	`false`	When `true`, returns `IError` on validation failure. When `false`, logs errors and returns original data
`logErrors`	`boolean`	`true`	Log validation errors to console (useful for debugging)

Validation Modes

Soft Mode (Default)

When strictMode is false, validation errors are logged to the console, but the original API response is returned unchanged. This is useful during development to identify potential data inconsistencies without breaking your application.

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,
    strictMode: false,  // Soft mode
    logErrors: true,
  }
})

// Even if validation fails, you'll get the API response
const user = await api.Users.getUser()
// Console will show validation errors if any

Strict Mode

When strictMode is true, validation failures return an IError object instead of the data. This ensures your application only processes validated data.

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,
    strictMode: true,   // Strict mode
    logErrors: true,
  }
})

const user = await api.Users.getUser()

// Check if response is an error
if ('statusCode' in user) {
  console.error('Validation failed:', user.message)
} else {
  // Type-safe: user is IUserEntity
  console.log('User:', user.email)
}

Errors

If you want to escape errors inside the sc, leave the "errors" property by default. In this case, you will receive either the entity data or the error object. You need to do a type check. for example, by checking the statusCode property with ".hasOwnProperty"

However, if you want to use the construction "try catch(e) ", set the property "isShell" to the value "false". In this case, you need to handle the error using "try catch(e) ".

Also, you can pass custom functions that will be called inside the sdk with the appropriate error code. These functions receive an error object as an argument. You can process it yourself.

const api = defineOneEntry('your-url', {
  token: 'my-token',
  langCode: 'my-langCode',
  errors: {
    isShell: false,
    customErrors: {
      400: (error) => console.error('Bad Request:', error.message),
      401: (error) => console.error('Unauthorized:', error.message),
      403: (error) => console.error('Forbidden:', error.message),
      404: (error) => console.error('Not Found:', error.message),
      429: (error) => console.error('Rate Limit Exceeded:', error.message),
      500: (error) => console.error('Server Error:', error.message),
      502: (error) => console.error('Bad Gateway:', error.message),
      503: (error) => console.error('Service Unavailable:', error.message),
      504: (error) => console.error('Gateway Timeout:', error.message),
    },
  },
})

When the isShell: false option is set in the SDK configuration, it has the following effect:

When an error occurs in API requests (e.g., HTTP errors 400, 401, 404, 500, etc., or network errors), the SDK will throw an exception instead of returning the error object as a normal value.

This allows you to use the try/catch construct in your application code to handle errors:

try {
  const result = await api.someMethod();
  // Handling a successful result
} catch (error) {
  // Error handling
}

If isShell: true, errors are returned as values, and you will need to explicitly check the result type to verify:

const result = await api.someMethod();
if ('statusCode' in result) { // Assumes the presence of a statusCode property on the error object
  // Error handling
} else {
  // Handling a successful result
}

Thus, isShell: false allows for a more familiar try/catch error handling model, while isShell: true provides a flat model where errors and success are returned as values of the same type.

When using the SDK with the default setting (isShell set to true), errors are returned as values rather than thrown as exceptions. This means the application won't crash due to unhandled exceptions, because errors are handled as part of the normal execution flow. Here's how you can handle errors on the front end without using try/catch:

Check the return type after calling an API method:

const result = await api.someMethod();

// Check if the result is an error
if ('statusCode' in result || 'message' in result) {
  // Error handling
  console.error('Error:', result);
} else {
  // Handling a successful result
  console.log('Success:', result);
}

You can also create use utils type "IError" to check for errors:

import type { IError } from '../base/utils';

function isErrorResult(result: any): result is IError {
  return result && typeof result === 'object' && 
         (result.hasOwnProperty('statusCode') || 
          result.hasOwnProperty('message'));
}

// Then use it like this:
const result = await api.someMethod();

if (isErrorResult(result)) {
  // Error handling
  console.error('Произошла ошибка:', result);
} else {
  // Handling a successful result
  console.log('Успешный результат:', result);
}

This approach allows you to avoid using try/catch constructs while still correctly handling errors, preventing the application from crashing.

📚 Next Steps

Explore our comprehensive guides to learn more:

🛍️

Get Started

🚀 Quick Start

1️⃣ Install the package

2️⃣ Initialize the SDK

3️⃣ Start using the API

✨ Key Features

🌐 Resources

📖 Detailed Usage

All Available Modules

Config

You can get a token as follows

API Response Validation

Features

Configuration

Configuration Options

Validation Modes

Soft Mode (Default)

Strict Mode

Errors

When the isShell: false option is set in the SDK configuration, it has the following effect:

📚 Next Steps

E-commerce

User Management

Orders & Checkout

Pages & Content

Forms

Forms data

Get Started

🚀 Quick Start​

1️⃣ Install the package​

2️⃣ Initialize the SDK​

3️⃣ Start using the API​

✨ Key Features​

🌐 Resources​

📖 Detailed Usage​

All Available Modules​

Config​

You can get a token as follows​

API Response Validation

Features​

Configuration​

Configuration Options​

Validation Modes​

Soft Mode (Default)​

Strict Mode​

Errors​

When the isShell: false option is set in the SDK configuration, it has the following effect:​

📚 Next Steps​

E-commerce

User Management

Orders & Checkout

Pages & Content

Forms

Forms data

🚀 Quick Start

1️⃣ Install the package

2️⃣ Initialize the SDK

3️⃣ Start using the API

✨ Key Features

🌐 Resources

📖 Detailed Usage

All Available Modules

Config

You can get a token as follows

Features

Configuration

Configuration Options

Validation Modes

Soft Mode (Default)

Strict Mode

Errors

When the isShell: false option is set in the SDK configuration, it has the following effect:

📚 Next Steps