MyOS Java SDK

Java SDK for the MyOS API, with first-class Blue DSL integration.

Features

• Single client entrypoint:
  • MyOsClient.builder().apiKey("...").build()
• Resource-based API surface:
  • documents(), timelines(), webhooks(), me(), apiKeys(), users(), myOsEvents(), integrations(), maintenance()
• Typed checked exception hierarchy:
  • MyOsException -> ApiException -> AuthenticationException, RateLimitException, ValidationException, NotFoundException, ServerException
• Sync + async methods (CompletableFuture) for all resource methods
• Retry with exponential backoff on 429 and 5xx
• Per-request options (RequestOptions) for custom headers/timeouts/retry override
• Native Blue Node document support (no extra DTO layer for document authoring)

Requirements

• Java 17+
• Gradle 8.10+

Dependency

<dependency>
  <groupId>blue.myos</groupId>
  <artifactId>myos-java-sdk</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>

The SDK depends on Blue Language Java:

<dependency>
  <groupId>blue.language</groupId>
  <artifactId>blue-language-java</artifactId>
  <version>0.8.0-SNAPSHOT</version>
</dependency>

Quickstart

Create a client

MyOsClient client = MyOsClient.builder()
    .apiKey("YOUR_API_KEY")
    .baseUrl("https://api.dev.myos.blue")
    .build();

Bootstrap a document with Blue DSL

Node document = DocBuilder.doc()
    .name("Purchase Approval")
    .channel("ownerChannel")
    .field("/status", "draft")
    .buildDocument();

BootstrapResponse response = client.documents().bootstrap(
    document,
    bindings -> bindings.bind("ownerChannel", "owner@example.com"),
    options -> options
        .message("You have been invited")
        .channelMessage("ownerChannel", "Please review and sign")
        .capability("sessionInteraction", true));

Bootstrap a PayNote

Note: PayNote is a Blue DSL document type, not a dedicated API resource.

Node payNote = PayNotes.payNote("Purchase")
    .currency("USD")
    .amountMinor(80000)
    .capture()
        .lockOnInit()
        .unlockOnOperation("confirm", "payerChannel", "Confirm delivery")
        .done()
    .buildDocument();

BootstrapResponse response = client.documents().bootstrap(
    payNote,
    bindings -> bindings
        .bind("payerChannel", "alice@example.com")
        .bind("payeeChannel", "merchant@example.com")
        .bind("guarantorChannel", "guarantor@example.com"));

Call operations and fetch state

OperationResponse op = client.documents().callOperation(response.getSessionId(), "confirm");
DocumentState state = client.documents().get(response.getSessionId());
List<String> allowed = state.getAllowedOperations();

Async usage

CompletableFuture<DocumentState> stateFuture =
    client.documents().getAsync("session-id");

Per-request overrides

RequestOptions options = RequestOptions.builder()
    .header("X-Trace-Id", "trace-123")
    .timeout(Duration.ofSeconds(10))
    .maxRetries(1)
    .build();

DocumentState state = client.documents().get("session-id", options);

Running tests

# Unit tests
./gradlew test

# Unit + E2E
./gradlew check -Pe2e=true