From a08237b0c5021dc2eb4b5b14c4e74566e3756ea6 Mon Sep 17 00:00:00 2001 From: OneSignal Date: Fri, 26 Jun 2026 19:43:25 +0000 Subject: [PATCH] docs: add AGENTS.md agent guide and absolute README links --- AGENTS.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 5 ++++ README.md | 2 ++ 3 files changed, 78 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fb0a06c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,71 @@ +# AGENTS.md — OneSignal Java SDK + +Integration guide for AI agents and LLMs using the OneSignal server SDK for Java. Human-oriented docs are in the [README](./README.md). + +## What this SDK does + +Server-side access to the OneSignal REST API: send push / email / SMS, manage users, subscriptions, segments, templates and live activities, and administer apps & API keys. + +- Maven coordinates: `com.onesignal:onesignal-java-client` (see the [README](./README.md) for the current version and Gradle setup) +- Repository: https://github.com/OneSignal/onesignal-java-api + +## Authentication — two key types + +OneSignal uses two bearer credentials; each endpoint requires a specific one. Both are registered on the `ApiClient` as named bearer-auth schemes: + +- **REST API key** (`rest_api_key`) — used by almost every endpoint (notifications, users, subscriptions, segments, templates, live activities, custom events). Found in **App Settings → Keys & IDs**. +- **Organization API key** (`organization_api_key`) — required *only* for organization-level endpoints: app management (list / create / get / update apps), API-key management (view / create / update / rotate / delete API keys), and copying a template to another app. Found in **Organization Settings**. + +Set both; the SDK sends the correct credential per endpoint. Never hard-code keys — read them from environment variables or a secrets manager. + +```java +import com.onesignal.client.ApiClient; +import com.onesignal.client.Configuration; +import com.onesignal.client.auth.HttpBearerAuth; +import com.onesignal.client.api.DefaultApi; + +ApiClient defaultClient = Configuration.getDefaultApiClient(); + +HttpBearerAuth restApiKey = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key"); +restApiKey.setBearerToken(System.getenv("ONESIGNAL_REST_API_KEY")); + +HttpBearerAuth orgApiKey = (HttpBearerAuth) defaultClient.getAuthentication("organization_api_key"); +orgApiKey.setBearerToken(System.getenv("ONESIGNAL_ORGANIZATION_API_KEY")); + +DefaultApi client = new DefaultApi(defaultClient); +``` + +## Calling convention + +Methods take **positional arguments**. Build the model object and pass it directly — do **not** wrap arguments in a request/options object. + +```java +Notification notification = new Notification(); +notification.setAppId("YOUR_APP_ID"); +LanguageStringMap contents = new LanguageStringMap(); +contents.setEn("Hello from OneSignal!"); +notification.setContents(contents); +Map> aliases = new HashMap<>(); +aliases.put("external_id", Arrays.asList("YOUR_USER_EXTERNAL_ID")); +notification.setIncludeAliases(aliases); +notification.setTargetChannel(Notification.TargetChannelEnum.PUSH); + +CreateNotificationSuccessResponse response = client.createNotification(notification); +``` + +## Idempotent sends & retries + +Set `idempotency_key` (a UUID) so a create-notification request can be safely retried — the server returns the original result instead of sending twice. The `createNotificationWithRetry` helper handles this for you: it generates an `idempotency_key` when absent, retries `429` / `503` / transport errors with the **same** key (honoring `Retry-After`), and reports via `getWasReplayed()` whether the server answered from a previously completed request. + +```java +NotificationHelpers.CreateNotificationWithRetryResult result = + client.createNotificationWithRetry(notification, 5, 1000L); +System.out.println("id: " + result.getResponse().getId() + " replayed: " + result.getWasReplayed()); +``` + +> The notification-level `external_id` field is the **deprecated** idempotency mechanism — prefer `idempotency_key`. Don't confuse it with the `external_id` **alias label** (under `include_aliases`) used to target users. + +## Full API reference + +- [DefaultApi.md](https://github.com/OneSignal/onesignal-java-api/blob/main/docs/DefaultApi.md) — every endpoint, parameter, and model, with runnable examples. +- [OneSignal REST API reference](https://documentation.onesignal.com/reference) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d3f6c39 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# CLAUDE.md + +AI agent and LLM integration guidance for this OneSignal server SDK lives in **[AGENTS.md](./AGENTS.md)** — authentication, calling conventions, idempotent retries, and the full API reference. + +See [AGENTS.md](./AGENTS.md). diff --git a/README.md b/README.md index 1a903c2..cd9de26 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # onesignal-java-client +> **Building with an AI agent or LLM?** See [AGENTS.md](https://github.com/OneSignal/onesignal-java-api/blob/main/AGENTS.md) for an agent-oriented integration guide — authentication, calling conventions, idempotent retries, and the full API reference. + OneSignal - API version: 5.8.0