@protectai/layer-sdk
v0.0.4
Published
JavaScript SDK for Protect AI's Layer.
Downloads
33
Readme
Layer SDK Node.js API library
Layer SDK is a Node.js library for interacting with the Layer API, allowing you to create sessions and append session actions with ease.
Installation
npm install layer-sdk
Configuration
The Layer SDK can be configured by passing configuration options directly when initializing the SDK.
import { LayerSDK } from 'layer-sdk';
const client = new LayerSDK(
'https://api.example.com',
'your-application-id',
'production',
[authMiddleware]
);
Configuration Options
baseUrl
: The base URL for the Layer API. This is where all API requests will be sent.applicationId
: Your unique application identifier provided by Layer.environment
: The environment you're operating in (e.g., "production", "development", "staging").middlewares
: An array of middleware objects, including authentication providers.
Quick Start
Here's a simple example of how to use the Layer SDK:
import {
LayerSDK,
OIDCClientCredentialsMiddleware,
SessionActionKind,
} from "layer-sdk";
const authMiddleware = new OIDCClientCredentialsMiddleware({
tokenUrl: "https://auth.example.com/token",
clientId: "your-client-id",
clientSecret: "your-client-secret",
scope: "your-scope",
});
const client = new LayerSDK(
"https://api.example.com",
"your-application-id",
"production",
[authMiddleware],
);
async function example() {
try {
// Create a session
const sessionId = await client.createSession({
attributes: { "user.id": "user-001" },
});
console.log(`Session ID: ${sessionId}`);
// Append an action
await client.appendAction(
sessionId,
SessionActionKind.COMPLETION_PROMPT,
new Date(),
new Date(Date.now() + 2000),
{ "model.id": "gpt-3.5-turbo-16k" },
{
messages: [
{ content: "Hello, how can I help you?", role: "assistant" },
],
},
);
} catch (error) {
console.error("Error:", error);
}
}
example();
Authentication
The Layer SDK supports optional authentication using OpenID Connect (OIDC) with Keycloak.
OIDC Authentication with Keycloak
If your Layer instance is configured to use OIDC authentication with Keycloak, you can set up the SDK to automatically handle authentication for you using the OIDCClientCredentialsMiddleware
.
Configuration Options:
tokenUrl
: The token endpoint URL for your Keycloak realm.clientId
: The client ID for your application, as registered in Keycloak.clientSecret
: The client secret for your application.scope
: The scope to request when obtaining an access token.
Using Without Authentication
If your Layer instance doesn't require authentication, you can initialize the Client without passing any middleware.
Resiliency
Error Handling
The SDK uses custom exception classes to provide clear and actionable error information:
LayerHTTPError
: Raised when an HTTP request fails. It includes the status code and error message from the server.LayerAuthError
: Raised if there's an authentication error.
Example of handling errors:
import { LayerSDK, LayerHTTPError } from "layer-sdk";
async function example() {
try {
const sessionId = await client.createSession({
attributes: { "user.id": "user-001" },
});
} catch (error) {
if (error instanceof LayerHTTPError) {
console.error(
`HTTP error occurred: Status ${error.status}, Message: ${error.message}`,
);
} else if (error instanceof LayerHTTPError) {
console.error(`Request error: ${error.message}`);
} else {
console.error(`Unexpected error: ${error}`);
}
}
}
Versioning
This package generally follows SemVer conventions, though certain backwards-incompatible changes may be released as minor versions:
- Changes that only affect static types, without breaking runtime behavior.
- Changes to library internals which are technically public but not intended or documented for external use. (Please open a GitHub issue to let us know if you are relying on such internals).
- Changes that we do not expect to impact the vast majority of users in practice.
We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
Requirements
Node.js 14 or higher.