Retter React Native SDK

React Native Client SDK for retter.io backend services.

Installation

Using npm:

npm install @retter/rn-sdk

Using yarn:

yarn add @retter/rn-sdk

Peer Dependencies

This package requires the following peer dependencies to be installed in your React Native project:

npm install @react-native-async-storage/async-storage
# or
yarn add @react-native-async-storage/async-storage

Important: This package uses @react-native-async-storage/async-storage as a peer dependency. If you use a bare React Native project, head over to the installation documents of this package. https://react-native-async-storage.github.io/async-storage/docs/install

Additionally, install React Native Firebase packages:

npm install @react-native-firebase/app @react-native-firebase/auth @react-native-firebase/firestore
# or
yarn add @react-native-firebase/app @react-native-firebase/auth @react-native-firebase/firestore

Note: Follow the official setup guides for React Native Firebase (iOS and Android) after installing the packages.

• App: https://rnfirebase.io/
• Auth: https://rnfirebase.io/auth/usage
• Firestore: https://rnfirebase.io/firestore/usage

Usage

Initialization

Clients should initialize with project id. Instances with same project id always be cached.

import Retter from '@retter/sdk'

const rio = Retter.getInstance(config: RetterClientConfig)

interface RetterClientConfig {
    projectId: string
    rootProjectId?: string
    region?: RetterRegion
    platform?: string
    culture?: string
    storage?: RetterStorage
}

projectId: Unique id of a project created in retter.io Console

region: Could be euWest1 or euWest1Beta

platform: ios, android, web, ...

culture: tr, en-US, vs....

storage: Optional async key/value adapter used to persist auth tokens. Defaults to AsyncStorage for backward compatibility, but JWTs and Firebase custom tokens should be kept in a secure store (iOS Keychain / Android Keystore). See below.

Secure Token Storage

By default the SDK persists access/refresh tokens via AsyncStorage. On rooted/jailbroken devices these are readable in plain text. Pass a SecureStore-backed adapter to keep them encrypted at rest:

import * as SecureStore from 'expo-secure-store'
import Retter, { RetterStorage } from '@retter/rn-sdk'

const secureStorage: RetterStorage = {
    getItem: (key) => SecureStore.getItemAsync(key),
    setItem: (key, value) => SecureStore.setItemAsync(key, value),
    removeItem: (key) => SecureStore.deleteItemAsync(key),
}

const rio = Retter.getInstance({
    projectId: 'YOUR_PROJECT_ID',
    storage: secureStorage,
})

For non-Expo projects, react-native-keychain works just as well — wrap its getGenericPassword / setGenericPassword / resetGenericPassword in the same RetterStorage shape.

Migration: when an existing app upgrades to 0.7.5+, the SDK reads the old plaintext blob from AsyncStorage on first launch, writes it to the configured storage and deletes the AsyncStorage entry. Users stay signed in.

iOS Keychain accessibility: expo-secure-store defaults to WHEN_UNLOCKED_THIS_DEVICE_ONLY, which closes audit finding MA-15 (no further config needed). If you want biometric/PIN gating on every token read, pass requireAuthentication: true from your adapter — note this prompts Face ID on every API call and significantly impacts UX.

Android note: SecureStore values are limited to ~2 KB. The SDK splits its payload across two keys (RIO_AUTH.<projectId> and RIO_FB.<projectId>) and stores only the raw tokens + clock-skew offset; decoded JWT payloads are reconstructed on read.

Authentication

Retter uses custom token to authenticate. This custom tokens can be given by an action or a cloud object.

await rio.authenticateWithCustomToken('{CUSTOM_TOKEN}')

Authentication statuses can be listened. SDK will fire an event that clients can be subscribe on status change.

rio.authStatus.subscribe((event: RetterAuthChangedEvent) => {
    //
})

Event gives information about current auth status. Clients can check the authStatus to determine if they need to show login/register pages or not.

interface RetterAuthChangedEvent {
    authStatus: RetterAuthStatus
    identity?: string
    uid?: string
    message?: string
}

enum RetterAuthStatus {
    SIGNED_IN = 'SIGNED_IN',
    SIGNED_IN_ANONYM = 'SIGNED_IN_ANONYM',
    SIGNED_OUT = 'SIGNED_OUT',
    AUTH_FAILED = 'AUTH_FAILED',
}

Cloud Objects

SDK will allow to use Retter Cloud Objects. Clients can subscribe realtime state changes, trigger cloud methods, ...

Firstly, a cloud object must be initilize with classId. Additional config options can be seen in interface below.

const cloudObject = await rio.getCloudObject(config: RetterCloudObjectConfig)

interface RetterCloudObjectConfig {
    classId: string
    key?: {
        name: string
        value: string
    }
    instanceId?: string
    method?: string
    headers?: {
        [key: string]: string
    }
    queryStringParams?: {
        [key: string]: string
    }
    body?: {
        [key: string]: any
    }
    httpMethod?: 'get' | 'delete' | 'post' | 'put'
    base64Encode?: boolean // default: true, only get requests
}

State Subscription

Clients can be subscribe to realtime state (public, user and role states) changes. On first subscription, it gives current state.

cloudObject.state.public.subscribe((state: { [key: string]: any }) => {
    //
})

cloudObject.state.user.subscribe((state: { [key: string]: any }) => {
    //
})

cloudObject.state.role.subscribe((state: { [key: string]: any }) => {
    //
})

Method Calls

Any cloud method can be called via sdk. method parameter must be specified. Other parameters can be seen in interface below.

const response = await cloudObject.call(params: RetterCloudObjectCall)

interface RetterCloudObjectCall {
    method: string
    headers?: {
        [key: string]: string
    }
    queryStringParams?: {
        [key: string]: string
    }
    body?: {
        [key: string]: any
    }
    httpMethod?: 'get' | 'delete' | 'post' | 'put' // default: post
    base64Encode?: boolean // default: true, only get requests
    retryConfig: {
        delay?: number // 50ms
        count?: number // 3
        rate?: number // 1.5
    }
}

Call method will return a response with RetterCallResponse type includes data, status and headers.

Getting State

Clients also access state via method call.

const response = await cloudObject.getState(params: RetterCloudObjectRequest)

interface RetterCloudObjectRequest {
    headers?: {
        [key: string]: string
    }
    queryStringParams?: {
        [key: string]: string
    }
    body?: {
        [key: string]: any
    }
    httpMethod?: 'get' | 'delete' | 'post' | 'put'
}

Get stae method will return a response with RetterCallResponse type includes data<RetterCloudObjectState>, status and headers.

Available Methods

Cloud objects available methods can be accessed on methods array/

const methods = cloudObject.methods: RetterCloudObjectMethod[]

interface RetterCloudObjectMethod {
    tag?: string
    name: string
    sync?: boolean
    readonly?: boolean
    inputModel?: string
    outputModel?: string
    queryStringModel?: string
}

Instance List

const instanceIds = await cloudObject.listInstances()