Skip to content
SlooseSloose

Publish a helper library

PUT
/orgs/{org}/libraries/{namespace}
curl --request PUT \
  --url https://api.sloose.com/orgs/org_9f3c/libraries/acme \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: "7"' \
  --data '{ "manifest": { "namespace": "example", "version": "example", "scope": "global", "description": "example", "functions": [ { "name": "example", "description": "example", "params": [ { "name": "example", "type": "example", "optional": true, "description": "example" } ], "returns": "example", "examples": [ { "call": "example", "result": "example" } ], "tags": [ "example" ] } ] }, "source": "example", "impactToken": "example" }'

Publishes the library as its next version (v1 for a new one). Before anything is written the manifest is validated against the helper manifest contract — its namespace must match the path and may not be core or the name of one of Sloose’s own helpers (trim, date…), which a library by that name would replace — and the source is compiled and loaded in the sandbox against that manifest, so a library that does not load is refused rather than stored. The library’s module, as the SDK writes it: import { defineLibrary } from '@sloose/sdk/library'; import manifest from '../manifest.json'; export default defineLibrary({ manifest, functions: { … } }); — those two imports and nothing else, one default export, JavaScript (the SDK strips TypeScript before it sends).

Sending what is already current publishes nothing: no new version, no change to the registry version, and published: false — so a push that sends the same library every time costs nothing. Every template, and every import that keeps no older version of it, uses the library as it currently is; an import may keep an older one by choice (libraryPins on the import), and nothing else pins.

Publishing is the helper_libraries plan feature (403 FEATURE_HELPER_LIBRARIES without it); reading and running a library are open on every plan.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org
required

The organisation id the session was issued for. A token for one organisation can never read another.

string
Example
org_9f3c

The organisation id the session was issued for. A token for one organisation can never read another.

namespace
required

The library namespace, as it appears in expressions.

string
Example
acme

The library namespace, as it appears in expressions.

Header Parameters

Section titled “Header Parameters”
If-Match

The registryVersion this change was made against, as "7" or 7 — a weak tag (W/"7") is refused, since If-Match uses strong comparison. Sent, the write is refused with 409 (code: REGISTRY_CONFLICT, the current version in the body) when the organisation has moved since, and otherwise answers the version it made: one past the version sent for a write made in one transaction, or the version sent itself for a request that asks for no change (an empty PATCH /config/writing), since it makes none. A bundle (POST /config/bundle) is several transactions and only its first waits on this version: it answers the version its own bumps took the organisation to — each part bumps only when it writes something, so a push of what is already there answers the version sent — and none — nor an etag — when another write landed between them; one landing after them, while its templates are saved, withholds the etag alone. Omitted, there is no condition, and * is no condition either — and a write with no condition answers no registryVersion (nor, from a bundle, an etag), since nothing says which version it was made from. A value that is neither is 400 (code: BAD_IF_MATCH) rather than ignored — a precondition silently dropped looks like conflict detection and is not.

string
Example
"7"

The registryVersion this change was made against, as "7" or 7 — a weak tag (W/"7") is refused, since If-Match uses strong comparison. Sent, the write is refused with 409 (code: REGISTRY_CONFLICT, the current version in the body) when the organisation has moved since, and otherwise answers the version it made: one past the version sent for a write made in one transaction, or the version sent itself for a request that asks for no change (an empty PATCH /config/writing), since it makes none. A bundle (POST /config/bundle) is several transactions and only its first waits on this version: it answers the version its own bumps took the organisation to — each part bumps only when it writes something, so a push of what is already there answers the version sent — and none — nor an etag — when another write landed between them; one landing after them, while its templates are saved, withholds the etag alone. Omitted, there is no condition, and * is no condition either — and a write with no condition answers no registryVersion (nor, from a bundle, an etag), since nothing says which version it was made from. A value that is neither is 400 (code: BAD_IF_MATCH) rather than ignored — a precondition silently dropped looks like conflict detection and is not.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
manifest
required
object
namespace
required
string
/^[a-z][a-z0-9_]*$/
version
required
string
/^\d+\.\d+\.\d+$/
scope
required
string
Allowed values: global org
description
string
functions
required
Array<object>
object
name
required
string
/^[A-Za-z_$][\w$]*$/
description
required
string
params
required
Array<object>
object
name
required
string
type
required
string
optional
boolean
description
string
returns
required
string
examples
Array<object>
object
call
required
string
result
string
tags
Array<string>
source
required

The library’s module, as the SDK writes it: import { defineLibrary } from '@sloose/sdk/library'; import manifest from '../manifest.json'; export default defineLibrary({ manifest, functions: { … } }); — those two imports and nothing else, one default export, JavaScript (the SDK strips TypeScript before it sends). At most 256 KB.

string
>= 1 characters <= 262144 characters
impactToken

The token of the POST …/impact answer the person confirmed. Sent, the publish checks what it would break again as it is made, and is refused 409 IMPACT_CHANGED — with the new answer — when that has changed. A caller that asked nothing (a repository’s push) sends none and is not checked.

string
>= 1 characters <= 128 characters

Responses

Section titled “Responses”

200

Section titled “200”

The library as it now stands, and — when the write was sent with If-Match — the registry version it is at: one past the version sent when it published, the version sent itself when it published nothing.

Media typeapplication/json
object
library
required
object
namespace
required
string
libraryId
required

The library’s own id. A name removed and published again is another library under a new id (#1040), so a page that changes who publishes it names this (PUT …/management), and an import’s kept version names it too (LibraryPin.library).

string
version
required

The manifest’s own semver: the author’s label, not which publish this is.

string
versionNumber
required

Which publish is current: 3 for v3 (…/versions). 0 for a library stored before versions were kept.

number
scope
required
string
Allowed values: global org
manifest
required
object
key
additional properties
source

The module as written, when the route answers it (?source=true on the list).

string
managedBy
required

sdk when the organisation’s configuration repository publishes it: its page is read only, and a person publishing, restoring or removing it is refused (409 LIBRARY_MANAGED) until it is taken over (PUT …/management), while an API token, which publishes as the repository, may. Null when people publish it on its page, where a push leaves it alone and says so and an API token is refused. A library a push or a token makes is the repository’s.

string | null
Allowed values: sdk
updatedAt
required
string
published
required

Whether this made a new version. False when what was sent is already current.

boolean
registryVersion

The version the organisation is at after this write, to send as the next write’s If-Match: one past the version you sent in If-Match for a write made in one transaction (a bundle, several, answers the version its own bumps took the organisation to, or none when another write landed between them), or that version itself for a request that asks for no change (an empty PATCH /config/writing, which writes nothing and makes no version; sending the value the organisation already has still writes, and moves it). Only a write sent with a version in If-Match answers one. Without (no header, or *), the write lands on whatever version the organisation is at, and nothing on the server knows which version your picture of the configuration was built from: another administrator’s change may be inside the number, and sent back as If-Match it would let your next write overwrite that change unseen. So it is left out. To write again, read the configuration first (its GET answers the version), or send If-Match.

number
Example
{
  "library": {
    "scope": "global",
    "managedBy": "sdk"
  }
}

400

Section titled “400”

The request — its body or its query — did not match the schema. issues carries the Zod issue list.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object
error
required

Human-readable explanation.

string
code

Machine-readable reason. Absent on a few legacy 400s.

string
key
additional properties
Examplegenerated
{
  "error": "example",
  "code": "example"
}

401

Section titled “401”

No bearer, or one that no longer resolves: a session that is unknown or expired (code: AUTH_REQUIRED), or an API token that was revoked or expired (TOKEN_REVOKED, TOKEN_EXPIRED), whose organisation is gone (ORG_NOT_FOUND) or whose member or user row is (MEMBERSHIP_GONE).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object
error
required

Human-readable explanation.

string
code

Machine-readable reason. Absent on a few legacy 400s.

string
key
additional properties
Examplegenerated
{
  "error": "example",
  "code": "example"
}

403

Section titled “403”

Not an administrator, or this plan cannot publish helper libraries (code: FEATURE_HELPER_LIBRARIES). Like every route behind a session: a session signed in but in no organisation is refused code: NO_ORG, a banned person code: BANNED, and a closed organisation code: ORG_CLOSED.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object
error
required

Human-readable explanation.

string
code

Machine-readable reason. Absent on a few legacy 400s.

string
key
additional properties
Examplegenerated
{
  "error": "example",
  "code": "example"
}

409

Section titled “409”

Or a bound on what an organisation’s libraries hold is met, the same on every plan (holding says where it stands with the caps, proposed what this would have brought it to): LIBRARY_LIMIT — it would hold more than 20 libraries; LIBRARIES_TOO_LARGE — its libraries would come to more than 1 MB of source; LIBRARY_HISTORY_FULL — the versions it keeps would come to more than 25 MB; LIBRARY_PUBLISH_RATE — more than 50 versions in 24 hours, counted from the first of them. A publish that changes nothing makes no version and meets none of them. Nothing was written. The organisation’s configuration has changed since the version in If-Match (REGISTRY_CONFLICT, the current one in the body); with impactToken, what the publish would break is no longer what the person confirmed (IMPACT_CHANGED, the new answer in impact); or the library is published by the other publisher (LIBRARY_MANAGED, which says who in managedBy): a person is refused one the configuration repository publishes — change it there, or take it over first (PUT …/management) — and an API token, which publishes as the repository, one taken over in the browser.

Media typeapplication/json
Any of:
object
error
required
string
code
required
string
Allowed values: REGISTRY_CONFLICT
registryVersion
required
number
key
additional properties
Example
{
  "code": "REGISTRY_CONFLICT"
}

422

Section titled “422”

The manifest’s namespace does not match the path, it declares global scope, it names core or one of Sloose’s own helpers (helpers.trim, helpers.date…), which a library by that name would replace, or the library does not load — error says what stopped it, with the line and column where there is one.

Media typeapplication/json
object
error
required
string
code
required
string
Allowed values: NAMESPACE_MISMATCH GLOBAL_LIBRARY RESERVED_NAMESPACE LIBRARY_DOES_NOT_LOAD
key
additional properties
Example
{
  "code": "NAMESPACE_MISMATCH"
}

503

Section titled “503”

Libraries cannot be checked just now: the sandbox did not answer (code: SANDBOX_UNAVAILABLE). Or the restore switch is on (code: MAINTENANCE): every route but /health and /robots.txt is refused before anything is read, with Retry-After (the operator’s ADMIN_TOKEN alone is let through to POST /staff/people/{id}/delete, and to nothing else).

Media typeapplication/json
One of:

The error envelope every non-2xx answer uses.

object
error
required

Human-readable explanation.

string
code

Machine-readable reason. Absent on a few legacy 400s.

string
key
additional properties
Example
{
  "code": "MAINTENANCE"
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds until asking again is worth it (300 while the switch is on).

Report a problem with this page

sloose.com