The worker

Your add-on's executable is a worker. Ledge starts it for each request, sends one JSON request, and reads one JSON response back.

One request, one response

  1. Ledge starts the executable.
  2. It writes one JSON request to standard input, then closes it.
  3. AddOnWorker.run reads the request and calls your handler.
  4. The worker writes one JSON response to standard output and exits.

Standard output carries only the response. Write anything else, such as diagnostics, to standard error, and never write tokens or whole requests there.

The request

FieldTypeMeaning
protocolVersionIntAlways 1. The worker rejects anything else before your handler runs.
operationStringWhat Ledge wants. Spotify Likes uses read and write.
trackIDStringThe Spotify ID of the song that's playing.
likedBool?For write, whether the song should be liked. Empty for read.
accessTokenStringA short-lived token for the provider, from Ledge's sign-in.
{"protocolVersion":1,"operation":"write","trackID":"4uLU6hMCjMI75M1A2tKUQC","liked":true,"accessToken":"…"}

The response

FieldTypeMeaning
valueBool?The answer. For Spotify Likes, whether the song is liked.
errorString?A short message for Ledge when the request failed. Leave it empty on success.
return AddOnResponse(value: true)
return AddOnResponse(value: nil, error: "Unsupported operation.")

When something goes wrong

If your handler throws, the worker replies with a generic error, “Add-on could not complete the request.” It never passes on the error's own text, because that can contain a token or a provider's response. Return your own error when you want Ledge to have something more specific, and keep it free of credentials.

Your handler must check its own inputs, such as the operation and the format of IDs, before acting on them.

Limits

  • A request can be at most 64 KB. Larger input is rejected before your handler runs.
  • Ledge decides how long a request may take and stops the worker when it's done. The worker has no timeout of its own.

Testing without an account

Keep the add-on's logic in a library target and give it a transport you can replace, so tests run without tokens or real accounts. AddOnWorker.respond(to:handler:) runs the whole worker on bytes in memory:

let input = try JSONEncoder().encode(
    AddOnRequest(operation: "read", trackID: "abc123", liked: nil, accessToken: "test"))
let response = await AddOnWorker.respond(to: input) { _ in AddOnResponse(value: true) }
#expect(response.value == true)