SDK Docs

The Norlax SDK is a wrapper around the API and makes working with it in Typescript a bit nicer. You can use the SDK to fetch data from Norlax, and to create a Norlax client.

Installation and Setup

To install the Norlax SDK, run the following command in your terminal:

npm install @Norlax/sdk

There are a few steps necessary to use the SDK in your app.

Create an account on Norlax if not already done.
Create a team if not already done.
Navigate to the Launchpads section and click the
+
button. For more information on how to create a launchpad, see Provide a public Launchpad.
Copy the Launchpad Id from the launchpad form and set it as an environment variable in your app. This is the default launchpad that will be used if no launchpad is specified in the request.

NORLAX_DEFAULT_LAUNCHPAD_SLUG_ID="*your-launchpad-slug-id-here*"

Be aware, that if you want to use the SDK from the client side, the launchpad id will be leaked to the client and can potentially be abused. This can be circumvented by only using the sdk on your server side, like we are doing in this documentation via server actions. You then should make sure to not name the environment variable NEXT_PUBLIC_NORLAX_DEFAULT_LAUNCHPAD_SLUG_ID but instead just NORLAX_DEFAULT_LAUNCHPAD_SLUG_ID if you are using Nextjs.

Api Reference

createNorlaxClient()

Create a Norlax Client with the following code:


import { createNorlaxClient } from "@Norlax/sdk"
import { env } from "./env.mjs"

export const Norlax = createNorlaxClient({
    default: {
      launchpadSlugId: env.NORLAX_DEFAULT_LAUNCHPAD_SLUG_ID,
    },
})

The createNorlaxClient function takes an object with the launchpads' names you want to configure as keys. The respective value is an object with the launchpadSlugId as a string. You can specify as many launchpads as you want.

The Norlax client object functions as a proxy for some of the other exported functions from the SDK, so you don't have to configure the respective

launchpadSlugId

for every request. There are four ways to retrieve data via the client object,

fetch

fetchData

fetchMedia

, and

fetchText

. Each of these proxy functions are explained more detailed in the following sections. You can get an idea of how to use the client object with the following code example. The commented out code shows the return type of the respective function:


  const completeResponse = await Norlax.default.fetch({ message: "Hi" })
  // completeResponse is of type
  // {
  //   message: {
  //       id: string;
  //       functionName?: string | undefined;
  //       content?: string | undefined;
  //       data?: undefined;
  //   };
  //   usage: {
  //       teamTokens: number;
  //   };
  //   chatroom: {
  //       id: string;
  //       url: string;
  //   };
  //   mediaAttachments?: {
  //       ...;
  //   }[] | undefined;
  //   cachedAt?: string | undefined;
  // }
  const formattedDataResponse = await Norlax.default.fetchData({
    message: "Hi",
    schema: z.object({
      greeting: z.string(),
      introduction: z.string(),
      question: z.string(),
      // ...
    }),
  })
  // Response is of type
  // {
  //   greeting: string;
  //   introduction: string;
  //   question: string;
  // }
  const mediaResponse = await Norlax.default.fetchMedia({ message: "Hi" })
  // Response is of type
  // {
  //   type: "AUDIO" | "IMAGE" | "DOCUMENT";
  //   id: string;
  //   url: string;
  // }
  const textResponse = await Norlax.default.fetchText({ message: "Hi" })
  // Response is of type string

fetchNorlax()

The fetchNorlax function resembles the proxy function

.fetch()

from the Norlax client object above. This is the default way to fetch data from Norlax. The function takes an object with the following parameters:

Name	Default	Description	Required
launchpadSlugId	Specified in the env vars by setting NORLAX_DEFAULT_LAUNCHPAD_SLUG_ID	The ID of the launchpad you want to use	Yes (unless default is set)
message		The message that gets sent to the AI	Yes
schema		The Zod schema which defines in which format you want the response	No
cacheTtlSeconds	Specified in the env vars by setting NORLAX_DEFAULT_CACHE_TTL_SECONDS or forever	The time in seconds results should be cached. The results are cached by your request parameters, so if you send the same request twice, the cache is triggered. Setting to 0 disables caching. Can also be set to 'forever'	No
chatroomId		If not set, a new chat is created. If you specify an existing chat, the message will be sent in that chat	No
accessLevel	TEAM	If a new chat is generated, this sets the access level. Options are 'TEAM' (only team members can view the chat), 'LINK_READ' (anyone with the link can read the chat), and 'LINK_WRITE' (anyone with the link can read and write in the chat)	No
customFunctions		You can pass custom functions the AI should have access to	No
customFunctionsMaxExecutions	10	Sets the max of how often custom functions can be called by the AI	No
functionExecution			No

fetchNorlaxData()

fetchNorlaxData is a wrapper function around fetchNorlax. It takes the same parameters as fetchNorlax, but only returns the data from the response. The function is useful if you don't want to deal with the complete response object and only want to work with the data.

fetchNorlaxText()

fetchNorlaxText is a wrapper function around fetchNorlax. It takes the same parameters as fetchNorlax, but only returns the text from the response. The function is useful if you don't want to deal with the complete response object and only want to work with the text.

fetchNorlaxMedia()

fetchNorlaxMedia is a wrapper function around fetchNorlax. It takes the same parameters as fetchNorlax, but only returns the first mediaAttachment from the response. The function is useful if you don't want to deal with the complete response object and only want to work with the media.

NorlaxFunctionHandler()

NorlaxFunctionHandler is a function designed to streamline the handling of HTTP requests for custom function execution. It sets up the necessary GET and POST request handling for you. This function should be used when you want to use HTTP Functions within Norlax. The function takes an object with the following parameters:

Name	Description	Required
functions	An array of NorlaxCustomFunction<any>[] defining the functions available for execution with their input schemas and execute methods.	Yes
functionSecret	A secret key that must match in the request headers under 'x-function-secret' for the request to be authorized.	No (unless used for auth)
checkAuthorization	An asynchronous function that takes a Request object and returns a boolean indicating whether the request is authorized.	No

transformZodToJsonSchema()

transformZodToJsonSchema is a function that takes a Zod schema and returns a JSON schema.