repository·master·Indexed 42 days ago
https://github.com/heroiclabs/nakama-jsA TypeScript-based JavaScript client for the Nakama server, designed for web browsers and React Native environments. It provides full API coverage, real-time socket capabilities, and an optional Protocol Buffers adapter via @heroiclabs/nakama-js-protobuf for improved WebSocket performance.
The generated code is designed to be lean and avoids heavy dependencies like Node's url package.
Dependencies:
fetch (may require a polyfill in certain environments).base64-js.Limitations:
A Session object contains the JWT token, a refreshToken, and user details. It is recommended to store the token and refresh token (e.g., in Web Storage) and check for expiry on startup.
To restore a session from stored tokens:
const authtoken = window.localStorage.getItem("nkauthtoken");
const refreshtoken = window.localStorage.getItem("nkrefreshtoken");
let session = nakamajs.Session.restore(authtoken, refreshtoken);To refresh an expired session:
if (session.isexpired(unixTimeInFuture / 1000)) {
try {
session = await client.sessionRefresh(session);
} catch (e) {
console.info("Session can no longer be refreshed. Must reauthenticate!");
}
}// Assume we've stored the auth token in browser Web Storage.
const authtoken = window.localStorage.getItem("nkauthtoken");
const refreshtoken = window.localStorage.getItem("nkrefreshtoken");
let session = nakamajs.Session.restore(authtoken, refreshtoken);
// Check whether a session is close to expiry.
const unixTimeInFuture = Date.now() + 8.64e+7; // one day from now
if (session.isexpired(unixTimeInFuture / 1000)) {
try
{
session = await client.sessionRefresh(session);
}
catch (e)
{
console.info("Session can no longer be refreshed. Must reauthenticate!");
}
}A Session object is returned upon successful authentication. It contains a JWT token, a refreshToken, and an expires_at timestamp (Unix time).
Key capabilities:
session.isexpired(unixTimestamp) to check if a session is no longer valid.Session.restore(authtoken, refreshtoken) to recreate a session from stored credentials (e.g., from Web Storage).client.sessionRefresh(session) to obtain a new session using a refresh token if the current one is near expiry.// Restore a session from storage
const authtoken = window.localStorage.getItem("satori_authtoken");
const refreshtoken = window.localStorage.getItem("satori_refreshtoken");
let session = satorijs.Session.restore(authtoken, refreshtoken);
// Check if session is close to expiry and refresh if necessary
const unixTimeInFuture = Date.now() + 8.64e+7; // one day from now
if (session.isexpired(unixTimeInFuture / 1000)) {
try {
session = await client.sessionRefresh(session);
} catch (e) {
console.info("Session can no longer be refreshed. Must reauthenticate!");
}
}Install the core client package via npm. This client is written in TypeScript and is compatible with modern browsers and React Native.
npm install @heroiclabs/nakama-jsTo add protocol buffer support to your nakama-js client, install the @heroiclabs/nakama-js-protobuf package using yarn.
yarn add "@heroiclabs/nakama-js-protobuf"If you want to use the Protocol Buffers wire format for your WebSocket connections (which can improve performance), install the optional adapter package:
npm install @heroiclabs/nakama-js-protobufyarn build and then open the resulting index.html file in your browser.yarn buildInstall the @heroiclabs/satori-js package via npm to use the Satori client in your browser or React Native project.
npm install @heroiclabs/satori-jsTo run the IIFE (Immediately Invoked Function Expression) example project, build the project using yarn build and then open the resulting index.html file in your browser.
yarn build
# Then open index.html in your browserYou can also use the openapi-gen utility to generate a TypeScript API client for Satori. Run the main.go file pointing to the Satori Swagger JSON file and specify "Satori" as the target name, redirecting the output to the satori-js package.
go run main.go "$GOPATH/src/github.com/heroiclabs/satori/api/satori.swagger.json" "Satori" > ../packages/satori-js/api.gen.tsTo use Protocol Buffers over WebSockets, import WebSocketAdapterPb from @heroiclabs/nakama-js-protobuf and pass an instance of it to client.createSocket(). This replaces the default JSON-based socket with one that supports Protobuf encoding/decoding.
import {Client} from "@heroiclabs/nakama-js";
import {WebSocketAdapterPb} from "@heroiclabs/nakama-js-protobuf"
const useSSL = false; // Enable if server is run with an SSL certificate.
const client = new Client("defaultkey", "127.0.0.1", 7350, useSSL);
const trace = false;
const socket = client.createSocket(useSSL, trace, new WebSocketAdapterPb());The openapi-gen utility is a command-line tool used to generate a TypeScript API client from a Nakama server's Swagger specification. This allows for the creation of lean, simple code with minimal dependencies compared to standard tools like swagger-codegen.
To generate the client, run the main.go file pointing to the Nakama Swagger JSON file and specify "Nakama" as the target name. The output should be redirected to the desired destination file in the nakama-js package.
go run main.go "$GOPATH/src/github.com/heroiclabs/nakama/apigrpc/apigrpc.swagger.json" "Nakama" > ../packages/nakama-js/api.gen.ts