@settlemint/sdk-utils
TypeScript icon, indicating that this package has built-in type declarations

1.2.2 • Public • Published

SettleMint logo

SettleMint SDK

https://settlemint.com
Integrate SettleMint into your application with ease.

CI status License npm stars

Documentation   •   NPM   •   Issues

Table of Contents

About

The SettleMint Utils SDK provides a collection of shared utilities and helper functions used across the SettleMint SDK packages. It includes common functionality for configuration management, error handling, validation, and type definitions that ensure consistency and reliability across the SDK ecosystem.

API Reference

Functions

ascii()

ascii(): void

Defined in: sdk/utils/src/terminal/ascii.ts:13

Prints the SettleMint ASCII art logo to the console in magenta color. Used for CLI branding and visual identification.

Returns

void

Example
import { ascii } from "@settlemint/sdk-utils/terminal";

// Prints the SettleMint logo
ascii();

camelCaseToWords()

camelCaseToWords(s): string

Defined in: sdk/utils/src/string.ts:29

Converts a camelCase string to a human-readable string.

Parameters
Parameter Type Description
s string The camelCase string to convert
Returns

string

The human-readable string

Example
import { camelCaseToWords } from "@settlemint/sdk-utils";

const words = camelCaseToWords("camelCaseString");
// Returns: "Camel Case String"

cancel()

cancel(msg): never

Defined in: sdk/utils/src/terminal/cancel.ts:23

Displays an error message in red inverse text and throws a CancelError. Used to terminate execution with a visible error message. Any sensitive tokens in the message are masked before display.

Parameters
Parameter Type Description
msg string The error message to display
Returns

never

never - Function does not return as it throws an error

Example
import { cancel } from "@settlemint/sdk-utils/terminal";

// Exits process with error message
cancel("An error occurred");

capitalizeFirstLetter()

capitalizeFirstLetter(val): string

Defined in: sdk/utils/src/string.ts:13

Capitalizes the first letter of a string.

Parameters
Parameter Type Description
val string The string to capitalize
Returns

string

The input string with its first letter capitalized

Example
import { capitalizeFirstLetter } from "@settlemint/sdk-utils";

const capitalized = capitalizeFirstLetter("hello");
// Returns: "Hello"

emptyDir()

emptyDir(dir): Promise<void>

Defined in: sdk/utils/src/package-manager/download-and-extract.ts:45

Removes all contents of a directory except the .git folder

Parameters
Parameter Type Description
dir string The directory path to empty
Returns

Promise<void>

Example
import { emptyDir } from "@settlemint/sdk-utils/package-manager";

await emptyDir("/path/to/dir"); // Removes all contents except .git

ensureBrowser()

ensureBrowser(): void

Defined in: sdk/utils/src/runtime/ensure-server.ts:31

Ensures that code is running in a browser environment and not on the server.

Returns

void

Throws

If called from a server environment

Example
import { ensureBrowser } from "@settlemint/sdk-utils/runtime";

// Will throw if running on server
ensureBrowser();

ensureServer()

ensureServer(): void

Defined in: sdk/utils/src/runtime/ensure-server.ts:13

Ensures that code is running on the server and not in a browser environment.

Returns

void

Throws

If called from a browser environment

Example
import { ensureServer } from "@settlemint/sdk-utils/runtime";

// Will throw if running in browser
ensureServer();

executeCommand()

executeCommand(command, args, options?): Promise<string[]>

Defined in: sdk/utils/src/terminal/execute-command.ts:31

Executes a command with the given arguments in a child process. Pipes stdin to the child process and captures stdout/stderr output. Masks any sensitive tokens in the output before displaying or returning.

Parameters
Parameter Type Description
command string The command to execute
args string[] Array of arguments to pass to the command
options? ExecuteCommandOptions Options for customizing command execution
Returns

Promise<string[]>

Array of output strings from stdout and stderr

Throws

If the process fails to start or exits with non-zero code

Example
import { executeCommand } from "@settlemint/sdk-utils/terminal";

// Execute git clone
await executeCommand("git", ["clone", "repo-url"]);

// Execute silently
await executeCommand("npm", ["install"], { silent: true });

exists()

exists(path): Promise<boolean>

Defined in: sdk/utils/src/filesystem/exists.ts:17

Checks if a file or directory exists at the given path

Parameters
Parameter Type Description
path PathLike The file system path to check for existence
Returns

Promise<boolean>

Promise that resolves to true if the path exists, false otherwise

Example
import { exists } from "@settlemint/sdk-utils/filesystem";

// Check if file exists before reading
if (await exists('/path/to/file.txt')) {
  // File exists, safe to read
}

fetchWithRetry()

fetchWithRetry(input, init?, maxRetries?, initialSleepTime?): Promise<Response>

Defined in: sdk/utils/src/http/fetch-with-retry.ts:18

Retry an HTTP request with exponential backoff and jitter. Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.

Parameters
Parameter Type Default value Description
input URL | RequestInfo undefined The URL or Request object to fetch
init? RequestInit undefined The fetch init options
maxRetries? number 5 Maximum number of retry attempts
initialSleepTime? number 3_000 Initial sleep time between retries in ms
Returns

Promise<Response>

The fetch Response

Throws

Error if all retries fail

Example
import { fetchWithRetry } from "@settlemint/sdk-utils/http";

const response = await fetchWithRetry("https://api.example.com/data");

findMonoRepoPackages()

findMonoRepoPackages(projectDir): Promise<string[]>

Defined in: sdk/utils/src/filesystem/mono-repo.ts:59

Finds all packages in a monorepo

Parameters
Parameter Type Description
projectDir string The directory to start searching from
Returns

Promise<string[]>

An array of package directories

Example
import { findMonoRepoPackages } from "@settlemint/sdk-utils/filesystem";

const packages = await findMonoRepoPackages("/path/to/your/project");
console.log(packages); // Output: ["/path/to/your/project/packages/core", "/path/to/your/project/packages/ui"]

findMonoRepoRoot()

findMonoRepoRoot(startDir): Promise<null | string>

Defined in: sdk/utils/src/filesystem/mono-repo.ts:19

Finds the root directory of a monorepo

Parameters
Parameter Type Description
startDir string The directory to start searching from
Returns

Promise<null | string>

The root directory of the monorepo or null if not found

Example
import { findMonoRepoRoot } from "@settlemint/sdk-utils/filesystem";

const root = await findMonoRepoRoot("/path/to/your/project");
console.log(root); // Output: /path/to/your/project/packages/core

formatTargetDir()

formatTargetDir(targetDir): string

Defined in: sdk/utils/src/package-manager/download-and-extract.ts:15

Formats a directory path by removing trailing slashes and whitespace

Parameters
Parameter Type Description
targetDir string The directory path to format
Returns

string

The formatted directory path

Example
import { formatTargetDir } from "@settlemint/sdk-utils/package-manager";

const formatted = formatTargetDir("/path/to/dir/ "); // "/path/to/dir"

getPackageManager()

getPackageManager(targetDir?): Promise<AgentName>

Defined in: sdk/utils/src/package-manager/get-package-manager.ts:15

Detects the package manager used in the current project

Parameters
Parameter Type Description
targetDir? string The directory to check for package manager (optional, defaults to process.cwd())
Returns

Promise<AgentName>

The name of the package manager

Example
import { getPackageManager } from "@settlemint/sdk-utils/package-manager";

const packageManager = await getPackageManager();
console.log(`Using ${packageManager}`);

getPackageManagerExecutable()

getPackageManagerExecutable(targetDir?): Promise<{ args: string[]; command: string; }>

Defined in: sdk/utils/src/package-manager/get-package-manager-executable.ts:14

Retrieves the executable command and arguments for the package manager

Parameters
Parameter Type Description
targetDir? string The directory to check for package manager (optional, defaults to process.cwd())
Returns

Promise<{ args: string[]; command: string; }>

An object containing the command and arguments for the package manager

Example
import { getPackageManagerExecutable } from "@settlemint/sdk-utils/package-manager";

const { command, args } = await getPackageManagerExecutable();
console.log(`Using ${command} with args: ${args.join(" ")}`);

graphqlFetchWithRetry()

graphqlFetchWithRetry<Data>(input, init?, maxRetries?, initialSleepTime?): Promise<Data>

Defined in: sdk/utils/src/http/graphql-fetch-with-retry.ts:34

Executes a GraphQL request with automatic retries using exponential backoff and jitter. Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors. Will also retry if the GraphQL response contains errors.

Type Parameters
Type Parameter
Data
Parameters
Parameter Type Default value Description
input URL | RequestInfo undefined The URL or Request object for the GraphQL endpoint
init? RequestInit undefined Optional fetch configuration options
maxRetries? number 5 Maximum retry attempts before failing (default: 5)
initialSleepTime? number 3_000 Initial delay between retries in milliseconds (default: 3000)
Returns

Promise<Data>

The parsed GraphQL response data

Throws

Error if all retries fail or if GraphQL response contains errors

Example
import { graphqlFetchWithRetry } from "@settlemint/sdk-utils/http";

const data = await graphqlFetchWithRetry<{ user: { id: string } }>(
  "https://api.example.com/graphql",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: `query GetUser($id: ID!) {
        user(id: $id) {
          id
        }
      }`,
      variables: { id: "123" }
    })
  }
);

installDependencies()

installDependencies(pkgs, cwd?): Promise<void>

Defined in: sdk/utils/src/package-manager/install-dependencies.ts:20

Installs one or more packages as dependencies using the detected package manager

Parameters
Parameter Type Description
pkgs string | string[] A single package name or array of package names to install
cwd? string The directory to run the installation in
Returns

Promise<void>

A promise that resolves when installation is complete

Throws

If package installation fails

Example
import { installDependencies } from "@settlemint/sdk-utils/package-manager";

// Install a single package
await installDependencies("express");

// Install multiple packages
await installDependencies(["express", "cors"]);

intro()

intro(msg): void

Defined in: sdk/utils/src/terminal/intro.ts:15

Displays an introductory message in magenta text with padding. Any sensitive tokens in the message are masked before display.

Parameters
Parameter Type Description
msg string The message to display as introduction
Returns

void

Example
import { intro } from "@settlemint/sdk-utils/terminal";

// Display intro message
intro("Starting deployment...");

isEmpty()

isEmpty(path): Promise<boolean>

Defined in: sdk/utils/src/package-manager/download-and-extract.ts:31

Checks if a directory is empty or contains only a .git folder

Parameters
Parameter Type Description
path string The directory path to check
Returns

Promise<boolean>

True if directory is empty or contains only .git, false otherwise

Example
import { isEmpty } from "@settlemint/sdk-utils/package-manager";

if (await isEmpty("/path/to/dir")) {
  // Directory is empty
}

isPackageInstalled()

isPackageInstalled(name, path?): Promise<boolean>

Defined in: sdk/utils/src/package-manager/is-package-installed.ts:17

Checks if a package is installed in the project's dependencies, devDependencies, or peerDependencies.

Parameters
Parameter Type Description
name string The name of the package to check
path? string The path to the project root directory. If not provided, will be automatically determined
Returns

Promise<boolean>

Whether the package is installed

Throws

If unable to read or parse the package.json file

Example
import { isPackageInstalled } from "@settlemint/sdk-utils/package-manager";

const isInstalled = await isPackageInstalled("@settlemint/sdk-utils");
console.log(`@settlemint/sdk-utils is installed: ${isInstalled}`);

list()

list(title, items): void

Defined in: sdk/utils/src/terminal/list.ts:23

Displays a list of items in a formatted manner, supporting nested items.

Parameters
Parameter Type Description
title string The title of the list
items (string | string[])[] The items to display, can be strings or arrays for nested items
Returns

void

The formatted list

Example
import { list } from "@settlemint/sdk-utils/terminal";

// Simple list
list("Use cases", ["use case 1", "use case 2", "use case 3"]);

// Nested list
list("Providers", [
  "AWS",
  ["us-east-1", "eu-west-1"],
  "Azure",
  ["eastus", "westeurope"]
]);

loadEnv()

loadEnv<T>(validateEnv, prod, path): Promise<T extends true ? object : object>

Defined in: sdk/utils/src/environment/load-env.ts:25

Loads environment variables from .env files. To enable encryption with dotenvx (https://www.dotenvx.com/docs) run bunx dotenvx encrypt

Type Parameters
Type Parameter Default type
T extends boolean true
Parameters
Parameter Type Description
validateEnv T Whether to validate the environment variables against the schema
prod boolean Whether to load production environment variables
path string Optional path to the directory containing .env files. Defaults to process.cwd()
Returns

Promise<T extends true ? object : object>

A promise that resolves to the validated environment variables

Throws

Will throw an error if validation fails and validateEnv is true

Example
import { loadEnv } from '@settlemint/sdk-utils/environment';

// Load and validate environment variables
const env = await loadEnv(true, false);
console.log(env.SETTLEMINT_INSTANCE);

// Load without validation
const rawEnv = await loadEnv(false, false);

maskTokens()

maskTokens(output): string

Defined in: sdk/utils/src/terminal/mask-tokens.ts:13

Masks sensitive SettleMint tokens in output text by replacing them with asterisks. Handles personal access tokens (PAT), application access tokens (AAT), and service account tokens (SAT).

Parameters
Parameter Type Description
output string The text string that may contain sensitive tokens
Returns

string

The text with any sensitive tokens masked with asterisks

Example
import { maskTokens } from "@settlemint/sdk-utils/terminal";

// Masks a token in text
const masked = maskTokens("Token: sm_pat_****"); // "Token: ***"

note()

note(message, level): void

Defined in: sdk/utils/src/terminal/note.ts:20

Displays a note message with optional warning level formatting. Regular notes are displayed in normal text, while warnings are shown in yellow. Any sensitive tokens in the message are masked before display.

Parameters
Parameter Type Default value Description
message string undefined The message to display as a note
level "info" | "warn" "info" The note level: "info" (default) or "warn" for warning styling
Returns

void

Example
import { note } from "@settlemint/sdk-utils/terminal";

// Display info note
note("Operation completed successfully");

// Display warning note
note("Low disk space remaining", "warn");

outro()

outro(msg): void

Defined in: sdk/utils/src/terminal/outro.ts:15

Displays a closing message in green inverted text with padding. Any sensitive tokens in the message are masked before display.

Parameters
Parameter Type Description
msg string The message to display as conclusion
Returns

void

Example
import { outro } from "@settlemint/sdk-utils/terminal";

// Display outro message
outro("Deployment completed successfully!");

projectRoot()

projectRoot(fallbackToCwd, cwd?): Promise<string>

Defined in: sdk/utils/src/filesystem/project-root.ts:18

Finds the root directory of the current project by locating the nearest package.json file

Parameters
Parameter Type Default value Description
fallbackToCwd boolean false If true, will return the current working directory if no package.json is found
cwd? string undefined The directory to start searching for the package.json file from (defaults to process.cwd())
Returns

Promise<string>

Promise that resolves to the absolute path of the project root directory

Throws

Will throw an error if no package.json is found in the directory tree

Example
import { projectRoot } from "@settlemint/sdk-utils/filesystem";

// Get project root path
const rootDir = await projectRoot();
console.log(`Project root is at: ${rootDir}`);

replaceUnderscoresAndHyphensWithSpaces()

replaceUnderscoresAndHyphensWithSpaces(s): string

Defined in: sdk/utils/src/string.ts:48

Replaces underscores and hyphens with spaces.

Parameters
Parameter Type Description
s string The string to replace underscores and hyphens with spaces
Returns

string

The input string with underscores and hyphens replaced with spaces

Example
import { replaceUnderscoresAndHyphensWithSpaces } from "@settlemint/sdk-utils";

const result = replaceUnderscoresAndHyphensWithSpaces("Already_Spaced-Second");
// Returns: "Already Spaced Second"

retryWhenFailed()

retryWhenFailed<T>(fn, maxRetries, initialSleepTime, stopOnError?): Promise<T>

Defined in: sdk/utils/src/retry.ts:14

Retry a function when it fails.

Type Parameters
Type Parameter
T
Parameters
Parameter Type Default value Description
fn () => Promise<T> undefined The function to retry.
maxRetries number 5 The maximum number of retries.
initialSleepTime number 1_000 The initial time to sleep between exponential backoff retries.
stopOnError? (error) => boolean undefined The function to stop on error.
Returns

Promise<T>

The result of the function or undefined if it fails.

Example
import { retryWhenFailed } from "@settlemint/sdk-utils";
import { readFile } from "node:fs/promises";

const result = await retryWhenFailed(() => readFile("/path/to/file.txt"), 3, 1_000);

setName()

setName(name, path?): Promise<void>

Defined in: sdk/utils/src/package-manager/set-name.ts:16

Sets the name field in the package.json file

Parameters
Parameter Type Description
name string The new name to set in the package.json file
path? string The path to the project root directory. If not provided, will be automatically determined
Returns

Promise<void>

A promise that resolves when the package.json has been updated

Throws

If unable to read, update or save the package.json file

Example
import { setName } from "@settlemint/sdk-utils/package-manager";

await setName("my-new-project-name");

spinner()

spinner<R>(options): Promise<R>

Defined in: sdk/utils/src/terminal/spinner.ts:54

Displays a loading spinner while executing an async task. Shows progress with start/stop messages and handles errors. Spinner is disabled in CI environments.

Type Parameters
Type Parameter
R
Parameters
Parameter Type Description
options SpinnerOptions<R> Configuration options for the spinner
Returns

Promise<R>

The result from the executed task

Throws

Will exit process with code 1 if task fails

Example
import { spinner } from "@settlemint/sdk-utils/terminal";

// Show spinner during async task
const result = await spinner({
  startMessage: "Deploying...",
  task: async () => {
    // Async work here
    return "success";
  },
  stopMessage: "Deployed successfully!"
});

table()

table(title, data): void

Defined in: sdk/utils/src/terminal/table.ts:20

Displays data in a formatted table in the terminal.

Parameters
Parameter Type Description
title string Title to display above the table
data unknown[] Array of objects to display in table format
Returns

void

Example
import { table } from "@settlemint/sdk-utils/terminal";

const data = [
  { name: "Item 1", value: 100 },
  { name: "Item 2", value: 200 }
];

table("My Table", data);

tryParseJson()

tryParseJson<T>(value, defaultValue): null | T

Defined in: sdk/utils/src/json.ts:23

Attempts to parse a JSON string into a typed value, returning a default value if parsing fails.

Type Parameters
Type Parameter
T
Parameters
Parameter Type Default value Description
value string undefined The JSON string to parse
defaultValue null | T null The value to return if parsing fails or results in null/undefined
Returns

null | T

The parsed JSON value as type T, or the default value if parsing fails

Example
import { tryParseJson } from "@settlemint/sdk-utils";

const config = tryParseJson<{ port: number }>(
  '{"port": 3000}',
  { port: 8080 }
);
// Returns: { port: 3000 }

const invalid = tryParseJson<string[]>(
  'invalid json',
  []
);
// Returns: []

validate()

validate<T>(schema, value): T["_output"]

Defined in: sdk/utils/src/validation/validate.ts:16

Validates a value against a given Zod schema.

Type Parameters
Type Parameter
T extends ZodType<any, ZodTypeDef, any>
Parameters
Parameter Type Description
schema T The Zod schema to validate against.
value unknown The value to validate.
Returns

T["_output"]

The validated and parsed value.

Throws

Will throw an error if validation fails, with formatted error messages.

Example
import { validate } from "@settlemint/sdk-utils/validation";

const validatedId = validate(IdSchema, "550e8400-e29b-41d4-a716-446655440000");

writeEnv()

writeEnv(options): Promise<void>

Defined in: sdk/utils/src/environment/write-env.ts:41

Writes environment variables to .env files across a project or monorepo

Parameters
Parameter Type Description
options { cwd: string; env: Partial<{ SETTLEMINT_ACCESS_TOKEN: string; SETTLEMINT_ACCESSIBLE_PRIVATE_KEY: string; SETTLEMINT_APPLICATION: string; SETTLEMINT_BLOCKCHAIN_NETWORK: string; SETTLEMINT_BLOCKCHAIN_NODE: string; SETTLEMINT_BLOCKSCOUT: string; SETTLEMINT_BLOCKSCOUT_GRAPHQL_ENDPOINT: string; SETTLEMINT_BLOCKSCOUT_UI_ENDPOINT: string; SETTLEMINT_CUSTOM_DEPLOYMENT: string; SETTLEMINT_CUSTOM_DEPLOYMENT_ENDPOINT: string; SETTLEMINT_HASURA: string; SETTLEMINT_HASURA_ADMIN_SECRET: string; SETTLEMINT_HASURA_DATABASE_URL: string; SETTLEMINT_HASURA_ENDPOINT: string; SETTLEMINT_HD_PRIVATE_KEY: string; SETTLEMINT_INSTANCE: string; SETTLEMINT_IPFS: string; SETTLEMINT_IPFS_API_ENDPOINT: string; SETTLEMINT_IPFS_GATEWAY_ENDPOINT: string; SETTLEMINT_IPFS_PINNING_ENDPOINT: string; SETTLEMINT_LOAD_BALANCER: string; SETTLEMINT_MINIO: string; SETTLEMINT_MINIO_ACCESS_KEY: string; SETTLEMINT_MINIO_ENDPOINT: string; SETTLEMINT_MINIO_SECRET_KEY: string; SETTLEMINT_NEW_PROJECT_NAME: string; SETTLEMINT_PORTAL: string; SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT: string; SETTLEMINT_PORTAL_REST_ENDPOINT: string; SETTLEMINT_THEGRAPH: string; SETTLEMINT_THEGRAPH_DEFAULT_SUBGRAPH: string; SETTLEMINT_THEGRAPH_SUBGRAPHS_ENDPOINTS: string[]; SETTLEMINT_WORKSPACE: string; }>; prod: boolean; secrets: boolean; } The options for writing the environment variables
options.cwd? string The directory to start searching for the package.json file from (defaults to process.cwd())
options.env Partial<{ SETTLEMINT_ACCESS_TOKEN: string; SETTLEMINT_ACCESSIBLE_PRIVATE_KEY: string; SETTLEMINT_APPLICATION: string; SETTLEMINT_BLOCKCHAIN_NETWORK: string; SETTLEMINT_BLOCKCHAIN_NODE: string; SETTLEMINT_BLOCKSCOUT: string; SETTLEMINT_BLOCKSCOUT_GRAPHQL_ENDPOINT: string; SETTLEMINT_BLOCKSCOUT_UI_ENDPOINT: string; SETTLEMINT_CUSTOM_DEPLOYMENT: string; SETTLEMINT_CUSTOM_DEPLOYMENT_ENDPOINT: string; SETTLEMINT_HASURA: string; SETTLEMINT_HASURA_ADMIN_SECRET: string; SETTLEMINT_HASURA_DATABASE_URL: string; SETTLEMINT_HASURA_ENDPOINT: string; SETTLEMINT_HD_PRIVATE_KEY: string; SETTLEMINT_INSTANCE: string; SETTLEMINT_IPFS: string; SETTLEMINT_IPFS_API_ENDPOINT: string; SETTLEMINT_IPFS_GATEWAY_ENDPOINT: string; SETTLEMINT_IPFS_PINNING_ENDPOINT: string; SETTLEMINT_LOAD_BALANCER: string; SETTLEMINT_MINIO: string; SETTLEMINT_MINIO_ACCESS_KEY: string; SETTLEMINT_MINIO_ENDPOINT: string; SETTLEMINT_MINIO_SECRET_KEY: string; SETTLEMINT_NEW_PROJECT_NAME: string; SETTLEMINT_PORTAL: string; SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT: string; SETTLEMINT_PORTAL_REST_ENDPOINT: string; SETTLEMINT_THEGRAPH: string; SETTLEMINT_THEGRAPH_DEFAULT_SUBGRAPH: string; SETTLEMINT_THEGRAPH_SUBGRAPHS_ENDPOINTS: string[]; SETTLEMINT_WORKSPACE: string; }> The environment variables to write
options.prod boolean Whether to write production environment variables
options.secrets boolean Whether to write to .env.local files for secrets
Returns

Promise<void>

Promise that resolves when writing is complete

Throws

Will throw an error if writing fails

Example
import { writeEnv } from '@settlemint/sdk-utils/environment';

// Write development environment variables
await writeEnv({
  prod: false,
  env: {
    SETTLEMINT_INSTANCE: 'https://dev.example.com'
  },
  secrets: false
});

// Write production secrets
await writeEnv({
  prod: true,
  env: {
    SETTLEMINT_ACCESS_TOKEN: 'secret-token'
  },
  secrets: true
});

Classes

CancelError

Defined in: sdk/utils/src/terminal/cancel.ts:8

Error class used to indicate that the operation was cancelled. This error is used to signal that the operation should be aborted.

Extends
  • Error

SpinnerError

Defined in: sdk/utils/src/terminal/spinner.ts:11

Error class used to indicate that the spinner operation failed. This error is used to signal that the operation should be aborted.

Extends
  • Error

Interfaces

ExecuteCommandOptions

Defined in: sdk/utils/src/terminal/execute-command.ts:7

Options for executing a command, extending SpawnOptionsWithoutStdio

Extends
  • SpawnOptionsWithoutStdio
Properties
Property Type Description Defined in
silent? boolean Whether to suppress output to stdout/stderr sdk/utils/src/terminal/execute-command.ts:9

SpinnerOptions<R>

Defined in: sdk/utils/src/terminal/spinner.ts:24

Options for configuring the spinner behavior

Type Parameters
Type Parameter
R
Properties
Property Type Description Defined in
startMessage string Message to display when spinner starts sdk/utils/src/terminal/spinner.ts:26
stopMessage string Message to display when spinner completes successfully sdk/utils/src/terminal/spinner.ts:30
task (spinner?: Spinner) => Promise<R> Async task to execute while spinner is active sdk/utils/src/terminal/spinner.ts:28

Type Aliases

AccessToken

AccessToken: string

Defined in: sdk/utils/src/validation/access-token.schema.ts:22

Schema for validating both application and personal access tokens. Accepts tokens starting with either 'sm_pat_' or 'sm_aat_' prefix.


ApplicationAccessToken

ApplicationAccessToken: string

Defined in: sdk/utils/src/validation/access-token.schema.ts:8

Schema for validating application access tokens. Application access tokens start with 'sm_aat_' prefix.


DotEnv

DotEnv: object

Defined in: sdk/utils/src/validation/dot-env.schema.ts:89

Type definition for the environment variables schema.

Type declaration
Name Type Description Defined in
SETTLEMINT_ACCESS_TOKEN? string Application access token for authenticating with SettleMint services sdk/utils/src/validation/dot-env.schema.ts:16
SETTLEMINT_ACCESSIBLE_PRIVATE_KEY? string Unique name of the accessible private key sdk/utils/src/validation/dot-env.schema.ts:55
SETTLEMINT_APPLICATION? string Unique name of the application sdk/utils/src/validation/dot-env.schema.ts:22
SETTLEMINT_BLOCKCHAIN_NETWORK? string Unique name of the blockchain network sdk/utils/src/validation/dot-env.schema.ts:24
SETTLEMINT_BLOCKCHAIN_NODE? string Unique name of the blockchain node sdk/utils/src/validation/dot-env.schema.ts:26
SETTLEMINT_BLOCKSCOUT? string Unique name of the Blockscout instance sdk/utils/src/validation/dot-env.schema.ts:77
SETTLEMINT_BLOCKSCOUT_GRAPHQL_ENDPOINT? string GraphQL endpoint URL for Blockscout sdk/utils/src/validation/dot-env.schema.ts:79
SETTLEMINT_BLOCKSCOUT_UI_ENDPOINT? string UI endpoint URL for Blockscout sdk/utils/src/validation/dot-env.schema.ts:81
SETTLEMINT_CUSTOM_DEPLOYMENT? string Unique name of the custom deployment sdk/utils/src/validation/dot-env.schema.ts:73
SETTLEMINT_CUSTOM_DEPLOYMENT_ENDPOINT? string Endpoint URL for the custom deployment sdk/utils/src/validation/dot-env.schema.ts:75
SETTLEMINT_HASURA? string Unique name of the Hasura instance sdk/utils/src/validation/dot-env.schema.ts:30
SETTLEMINT_HASURA_ADMIN_SECRET? string Admin secret for authenticating with Hasura sdk/utils/src/validation/dot-env.schema.ts:34
SETTLEMINT_HASURA_DATABASE_URL? string Database connection URL for Hasura sdk/utils/src/validation/dot-env.schema.ts:36
SETTLEMINT_HASURA_ENDPOINT? string Endpoint URL for the Hasura GraphQL API sdk/utils/src/validation/dot-env.schema.ts:32
SETTLEMINT_HD_PRIVATE_KEY? string Unique name of the HD private key sdk/utils/src/validation/dot-env.schema.ts:53
SETTLEMINT_INSTANCE string Base URL of the SettleMint platform instance sdk/utils/src/validation/dot-env.schema.ts:14
SETTLEMINT_IPFS? string Unique name of the IPFS instance sdk/utils/src/validation/dot-env.schema.ts:65
SETTLEMINT_IPFS_API_ENDPOINT? string API endpoint URL for IPFS sdk/utils/src/validation/dot-env.schema.ts:67
SETTLEMINT_IPFS_GATEWAY_ENDPOINT? string Gateway endpoint URL for IPFS sdk/utils/src/validation/dot-env.schema.ts:71
SETTLEMINT_IPFS_PINNING_ENDPOINT? string Pinning service endpoint URL for IPFS sdk/utils/src/validation/dot-env.schema.ts:69
SETTLEMINT_LOAD_BALANCER? string Unique name of the load balancer sdk/utils/src/validation/dot-env.schema.ts:28
SETTLEMINT_MINIO? string Unique name of the MinIO instance sdk/utils/src/validation/dot-env.schema.ts:57
SETTLEMINT_MINIO_ACCESS_KEY? string Access key for MinIO authentication sdk/utils/src/validation/dot-env.schema.ts:61
SETTLEMINT_MINIO_ENDPOINT? string Endpoint URL for MinIO sdk/utils/src/validation/dot-env.schema.ts:59
SETTLEMINT_MINIO_SECRET_KEY? string Secret key for MinIO authentication sdk/utils/src/validation/dot-env.schema.ts:63
SETTLEMINT_NEW_PROJECT_NAME? string Name of the new project being created sdk/utils/src/validation/dot-env.schema.ts:83
SETTLEMINT_PORTAL? string Unique name of the Smart Contract Portal instance sdk/utils/src/validation/dot-env.schema.ts:47
SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT? string GraphQL endpoint URL for the Portal sdk/utils/src/validation/dot-env.schema.ts:49
SETTLEMINT_PORTAL_REST_ENDPOINT? string REST endpoint URL for the Portal sdk/utils/src/validation/dot-env.schema.ts:51
SETTLEMINT_THEGRAPH? string Unique name of The Graph instance sdk/utils/src/validation/dot-env.schema.ts:38
SETTLEMINT_THEGRAPH_DEFAULT_SUBGRAPH? string Default The Graph subgraph to use sdk/utils/src/validation/dot-env.schema.ts:45
SETTLEMINT_THEGRAPH_SUBGRAPHS_ENDPOINTS? string[] Array of endpoint URLs for The Graph subgraphs sdk/utils/src/validation/dot-env.schema.ts:40
SETTLEMINT_WORKSPACE? string Unique name of the workspace sdk/utils/src/validation/dot-env.schema.ts:20

DotEnvPartial

DotEnvPartial: object

Defined in: sdk/utils/src/validation/dot-env.schema.ts:100

Type definition for the partial environment variables schema.

Type declaration
Name Type Description Defined in
SETTLEMINT_ACCESS_TOKEN? string Application access token for authenticating with SettleMint services sdk/utils/src/validation/dot-env.schema.ts:16
SETTLEMINT_ACCESSIBLE_PRIVATE_KEY? string Unique name of the accessible private key sdk/utils/src/validation/dot-env.schema.ts:55
SETTLEMINT_APPLICATION? string Unique name of the application sdk/utils/src/validation/dot-env.schema.ts:22
SETTLEMINT_BLOCKCHAIN_NETWORK? string Unique name of the blockchain network sdk/utils/src/validation/dot-env.schema.ts:24
SETTLEMINT_BLOCKCHAIN_NODE? string Unique name of the blockchain node sdk/utils/src/validation/dot-env.schema.ts:26
SETTLEMINT_BLOCKSCOUT? string Unique name of the Blockscout instance sdk/utils/src/validation/dot-env.schema.ts:77
SETTLEMINT_BLOCKSCOUT_GRAPHQL_ENDPOINT? string GraphQL endpoint URL for Blockscout sdk/utils/src/validation/dot-env.schema.ts:79
SETTLEMINT_BLOCKSCOUT_UI_ENDPOINT? string UI endpoint URL for Blockscout sdk/utils/src/validation/dot-env.schema.ts:81
SETTLEMINT_CUSTOM_DEPLOYMENT? string Unique name of the custom deployment sdk/utils/src/validation/dot-env.schema.ts:73
SETTLEMINT_CUSTOM_DEPLOYMENT_ENDPOINT? string Endpoint URL for the custom deployment sdk/utils/src/validation/dot-env.schema.ts:75
SETTLEMINT_HASURA? string Unique name of the Hasura instance sdk/utils/src/validation/dot-env.schema.ts:30
SETTLEMINT_HASURA_ADMIN_SECRET? string Admin secret for authenticating with Hasura sdk/utils/src/validation/dot-env.schema.ts:34
SETTLEMINT_HASURA_DATABASE_URL? string Database connection URL for Hasura sdk/utils/src/validation/dot-env.schema.ts:36
SETTLEMINT_HASURA_ENDPOINT? string Endpoint URL for the Hasura GraphQL API sdk/utils/src/validation/dot-env.schema.ts:32
SETTLEMINT_HD_PRIVATE_KEY? string Unique name of the HD private key sdk/utils/src/validation/dot-env.schema.ts:53
SETTLEMINT_INSTANCE? string Base URL of the SettleMint platform instance sdk/utils/src/validation/dot-env.schema.ts:14
SETTLEMINT_IPFS? string Unique name of the IPFS instance sdk/utils/src/validation/dot-env.schema.ts:65
SETTLEMINT_IPFS_API_ENDPOINT? string API endpoint URL for IPFS sdk/utils/src/validation/dot-env.schema.ts:67
SETTLEMINT_IPFS_GATEWAY_ENDPOINT? string Gateway endpoint URL for IPFS sdk/utils/src/validation/dot-env.schema.ts:71
SETTLEMINT_IPFS_PINNING_ENDPOINT? string Pinning service endpoint URL for IPFS sdk/utils/src/validation/dot-env.schema.ts:69
SETTLEMINT_LOAD_BALANCER? string Unique name of the load balancer sdk/utils/src/validation/dot-env.schema.ts:28
SETTLEMINT_MINIO? string Unique name of the MinIO instance sdk/utils/src/validation/dot-env.schema.ts:57
SETTLEMINT_MINIO_ACCESS_KEY? string Access key for MinIO authentication sdk/utils/src/validation/dot-env.schema.ts:61
SETTLEMINT_MINIO_ENDPOINT? string Endpoint URL for MinIO sdk/utils/src/validation/dot-env.schema.ts:59
SETTLEMINT_MINIO_SECRET_KEY? string Secret key for MinIO authentication sdk/utils/src/validation/dot-env.schema.ts:63
SETTLEMINT_NEW_PROJECT_NAME? string Name of the new project being created sdk/utils/src/validation/dot-env.schema.ts:83
SETTLEMINT_PORTAL? string Unique name of the Smart Contract Portal instance sdk/utils/src/validation/dot-env.schema.ts:47
SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT? string GraphQL endpoint URL for the Portal sdk/utils/src/validation/dot-env.schema.ts:49
SETTLEMINT_PORTAL_REST_ENDPOINT? string REST endpoint URL for the Portal sdk/utils/src/validation/dot-env.schema.ts:51
SETTLEMINT_THEGRAPH? string Unique name of The Graph instance sdk/utils/src/validation/dot-env.schema.ts:38
SETTLEMINT_THEGRAPH_DEFAULT_SUBGRAPH? string Default The Graph subgraph to use sdk/utils/src/validation/dot-env.schema.ts:45
SETTLEMINT_THEGRAPH_SUBGRAPHS_ENDPOINTS? string[] Array of endpoint URLs for The Graph subgraphs sdk/utils/src/validation/dot-env.schema.ts:40
SETTLEMINT_WORKSPACE? string Unique name of the workspace sdk/utils/src/validation/dot-env.schema.ts:20

Id

Id: string

Defined in: sdk/utils/src/validation/id.schema.ts:30

Type definition for database IDs, inferred from IdSchema. Can be either a PostgreSQL UUID string or MongoDB ObjectID string.


PersonalAccessToken

PersonalAccessToken: string

Defined in: sdk/utils/src/validation/access-token.schema.ts:15

Schema for validating personal access tokens. Personal access tokens start with 'sm_pat_' prefix.


Url

Url: string

Defined in: sdk/utils/src/validation/url.schema.ts:18

Schema for validating URLs.

Example
import { UrlSchema } from "@settlemint/sdk-utils/validation";

// Validate a URL
const isValidUrl = UrlSchema.safeParse("https://console.settlemint.com").success;
// true

// Invalid URLs will fail validation
const isInvalidUrl = UrlSchema.safeParse("not-a-url").success;
// false

UrlOrPath

UrlOrPath: string

Defined in: sdk/utils/src/validation/url.schema.ts:55

Schema that accepts either a full URL or a URL path.

Example
import { UrlOrPathSchema } from "@settlemint/sdk-utils/validation";

// Validate a URL
const isValidUrl = UrlOrPathSchema.safeParse("https://console.settlemint.com").success;
// true

// Validate a path
const isValidPath = UrlOrPathSchema.safeParse("/api/v1/users").success;
// true

UrlPath

UrlPath: string

Defined in: sdk/utils/src/validation/url.schema.ts:38

Schema for validating URL paths.

Example
import { UrlPathSchema } from "@settlemint/sdk-utils/validation";

// Validate a URL path
const isValidPath = UrlPathSchema.safeParse("/api/v1/users").success;
// true

// Invalid paths will fail validation
const isInvalidPath = UrlPathSchema.safeParse("not-a-path").success;
// false

Variables

AccessTokenSchema

const AccessTokenSchema: ZodString<AccessToken>

Defined in: sdk/utils/src/validation/access-token.schema.ts:21

Schema for validating both application and personal access tokens. Accepts tokens starting with either 'sm_pat_' or 'sm_aat_' prefix.


ApplicationAccessTokenSchema

const ApplicationAccessTokenSchema: ZodString<ApplicationAccessToken>

Defined in: sdk/utils/src/validation/access-token.schema.ts:7

Schema for validating application access tokens. Application access tokens start with 'sm_aat_' prefix.


DotEnvSchema

const DotEnvSchema: ZodObject<DotEnv>

Defined in: sdk/utils/src/validation/dot-env.schema.ts:12

Schema for validating environment variables used by the SettleMint SDK. Defines validation rules and types for configuration values like URLs, access tokens, workspace names, and service endpoints.


DotEnvSchemaPartial

const DotEnvSchemaPartial: ZodObject<DotEnvPartial>

Defined in: sdk/utils/src/validation/dot-env.schema.ts:95

Partial version of the environment variables schema where all fields are optional. Useful for validating incomplete configurations during development or build time.


IdSchema

const IdSchema: ZodUnion<Id>

Defined in: sdk/utils/src/validation/id.schema.ts:17

Schema for validating database IDs. Accepts both PostgreSQL UUIDs and MongoDB ObjectIDs. PostgreSQL UUIDs are 32 hexadecimal characters with hyphens (e.g. 123e4567-e89b-12d3-a456-426614174000). MongoDB ObjectIDs are 24 hexadecimal characters (e.g. 507f1f77bcf86cd799439011).

Example
import { IdSchema } from "@settlemint/sdk-utils/validation";

// Validate PostgreSQL UUID
const isValidUuid = IdSchema.safeParse("123e4567-e89b-12d3-a456-426614174000").success;

// Validate MongoDB ObjectID
const isValidObjectId = IdSchema.safeParse("507f1f77bcf86cd799439011").success;

PersonalAccessTokenSchema

const PersonalAccessTokenSchema: ZodString<PersonalAccessToken>

Defined in: sdk/utils/src/validation/access-token.schema.ts:14

Schema for validating personal access tokens. Personal access tokens start with 'sm_pat_' prefix.


runsInBrowser

const runsInBrowser: boolean = isBrowser

Defined in: sdk/utils/src/runtime/ensure-server.ts:40

Boolean indicating if code is currently running in a browser environment


runsOnServer

const runsOnServer: boolean = !isBrowser

Defined in: sdk/utils/src/runtime/ensure-server.ts:45

Boolean indicating if code is currently running in a server environment


UniqueNameSchema

const UniqueNameSchema: ZodString

Defined in: sdk/utils/src/validation/unique-name.schema.ts:19

Schema for validating unique names used across the SettleMint platform. Only accepts lowercase alphanumeric characters and hyphens. Used for workspace names, application names, service names etc.

Example
import { UniqueNameSchema } from "@settlemint/sdk-utils/validation";

// Validate a workspace name
const isValidName = UniqueNameSchema.safeParse("my-workspace-123").success;
// true

// Invalid names will fail validation
const isInvalidName = UniqueNameSchema.safeParse("My Workspace!").success;
// false

UrlOrPathSchema

const UrlOrPathSchema: ZodUnion<UrlOrPath>

Defined in: sdk/utils/src/validation/url.schema.ts:54

Schema that accepts either a full URL or a URL path.

Example
import { UrlOrPathSchema } from "@settlemint/sdk-utils/validation";

// Validate a URL
const isValidUrl = UrlOrPathSchema.safeParse("https://console.settlemint.com").success;
// true

// Validate a path
const isValidPath = UrlOrPathSchema.safeParse("/api/v1/users").success;
// true

UrlPathSchema

const UrlPathSchema: ZodString<UrlPath>

Defined in: sdk/utils/src/validation/url.schema.ts:34

Schema for validating URL paths.

Example
import { UrlPathSchema } from "@settlemint/sdk-utils/validation";

// Validate a URL path
const isValidPath = UrlPathSchema.safeParse("/api/v1/users").success;
// true

// Invalid paths will fail validation
const isInvalidPath = UrlPathSchema.safeParse("not-a-path").success;
// false

UrlSchema

const UrlSchema: ZodString<Url>

Defined in: sdk/utils/src/validation/url.schema.ts:17

Schema for validating URLs.

Example
import { UrlSchema } from "@settlemint/sdk-utils/validation";

// Validate a URL
const isValidUrl = UrlSchema.safeParse("https://console.settlemint.com").success;
// true

// Invalid URLs will fail validation
const isInvalidUrl = UrlSchema.safeParse("not-a-url").success;
// false

Contributing

We welcome contributions from the community! Please check out our Contributing guide to learn how you can help improve the SettleMint SDK through bug reports, feature requests, documentation updates, or code contributions.

License

The SettleMint SDK is released under the FSL Software License. See the LICENSE file for more details.

Package Sidebar

Install

npm i @settlemint/sdk-utils

Weekly Downloads

11,893

Version

1.2.2

License

FSL-1.1-MIT

Unpacked Size

512 kB

Total Files

51

Last publish

Collaborators

  • roderik
  • patrickmualaba
  • janb87