diff --git a/api/openapi.yaml b/api/openapi.yaml index 7bb44f7..af65810 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -64,6 +64,20 @@ paths: example: 0 type: integer style: form + - description: "Time-offset pagination cursor for sequential pulls of all messages.\ + \ Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`)\ + \ or the opaque Base64 cursor token returned as `next_time_offset` in a\ + \ prior response. When set, results are sorted ascending by send_after\ + \ and the standard `offset` parameter cannot be used. Repeat the request\ + \ with each `next_time_offset` until an empty notifications array is returned." + explode: true + in: query + name: time_offset + required: false + schema: + example: 2025-01-01T00:00:00.000Z + type: string + style: form responses: "200": content: @@ -3000,8 +3014,10 @@ components: NotificationSlice: example: offset: 6 + time_offset: time_offset total_count: 0 limit: 1 + next_time_offset: next_time_offset notifications: - null - null @@ -3012,6 +3028,14 @@ components: type: integer limit: type: integer + time_offset: + description: "The time_offset cursor specified in the request, if any." + type: string + next_time_offset: + description: An opaque Base64 cursor token representing the next page of + messages to fetch. Present when time_offset was provided in the request. Pass + this value as time_offset on the next request to continue paginating. + type: string notifications: items: $ref: '#/components/schemas/NotificationWithMeta' @@ -3685,9 +3709,12 @@ components: errors: "" properties: id: - description: Notification identifier when the request created a notification. - An empty string means no notification was created; read `errors` for details - (HTTP may still be 200). + description: "Notification identifier when the request created a notification.\ + \ An empty string means no notification was created; read `errors` for\ + \ details (HTTP may still be 200). All OneSignal server SDKs expose message-sent\ + \ / message-not-sent narrowing helpers (named idiomatically per language\ + \ — e.g. `isMessageSent`, `is_message_sent`, `message_sent?`); prefer\ + \ them over comparing `id` directly." type: string external_id: description: Optional correlation / idempotency-related value from the API diff --git a/docs/CreateNotificationSuccessResponse.md b/docs/CreateNotificationSuccessResponse.md index ff1e64e..1e59d72 100644 --- a/docs/CreateNotificationSuccessResponse.md +++ b/docs/CreateNotificationSuccessResponse.md @@ -7,7 +7,7 @@ | Name | Type | Description | Notes | |------------ | ------------- | ------------- | -------------| -|**id** | **String** | Notification identifier when the request created a notification. An empty string means no notification was created; read `errors` for details (HTTP may still be 200). | [optional] | +|**id** | **String** | Notification identifier when the request created a notification. An empty string means no notification was created; read `errors` for details (HTTP may still be 200). All OneSignal server SDKs expose message-sent / message-not-sent narrowing helpers (named idiomatically per language — e.g. `isMessageSent`, `is_message_sent`, `message_sent?`); prefer them over comparing `id` directly. | [optional] | |**externalId** | **String** | Optional correlation / idempotency-related value from the API response. This is not the end-user External ID used for targeting recipients (that lives under `include_aliases.external_id`). | [optional] | |**errors** | **Object** | Polymorphic field: may be an array of human-readable strings and/or an object (for example with `invalid_aliases`, `invalid_external_user_ids`, or `invalid_player_ids`) depending on the API response; HTTP may still be 200 with partial success. Typed SDKs model this loosely so both shapes deserialize. | [optional] | diff --git a/docs/DefaultApi.md b/docs/DefaultApi.md index 3b1e532..5a1b576 100644 --- a/docs/DefaultApi.md +++ b/docs/DefaultApi.md @@ -2135,7 +2135,7 @@ public class Example { # **getNotifications** -> NotificationSlice getNotifications(appId, limit, offset, kind) +> NotificationSlice getNotifications(appId, limit, offset, kind, timeOffset) View notifications @@ -2165,8 +2165,9 @@ public class Example { Integer limit = 10; // Integer | How many notifications to return. Max is 50. Default is 50. Integer offset = 0; // Integer | Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. Integer kind = 0; // Integer | Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only + String timeOffset = "2025-01-01T00:00:00.000Z"; // String | Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. try { - NotificationSlice result = apiInstance.getNotifications(appId, limit, offset, kind); + NotificationSlice result = apiInstance.getNotifications(appId, limit, offset, kind, timeOffset); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling DefaultApi#getNotifications"); @@ -2190,6 +2191,7 @@ public class Example { | **limit** | **Integer**| How many notifications to return. Max is 50. Default is 50. | [optional] | | **offset** | **Integer**| Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. | [optional] | | **kind** | **Integer**| Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only | [optional] [enum: 0, 1, 3] | +| **timeOffset** | **String**| Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. | [optional] | ### Return type diff --git a/docs/NotificationSlice.md b/docs/NotificationSlice.md index 5392a03..8ce0674 100644 --- a/docs/NotificationSlice.md +++ b/docs/NotificationSlice.md @@ -10,6 +10,8 @@ |**totalCount** | **Integer** | | [optional] | |**offset** | **Integer** | | [optional] | |**limit** | **Integer** | | [optional] | +|**timeOffset** | **String** | The time_offset cursor specified in the request, if any. | [optional] | +|**nextTimeOffset** | **String** | An opaque Base64 cursor token representing the next page of messages to fetch. Present when time_offset was provided in the request. Pass this value as time_offset on the next request to continue paginating. | [optional] | |**notifications** | [**List<NotificationWithMeta>**](NotificationWithMeta.md) | | [optional] | diff --git a/src/main/java/com/onesignal/client/NotificationHelpers.java b/src/main/java/com/onesignal/client/NotificationHelpers.java index a7b9e8a..1087228 100644 --- a/src/main/java/com/onesignal/client/NotificationHelpers.java +++ b/src/main/java/com/onesignal/client/NotificationHelpers.java @@ -103,6 +103,34 @@ public static CreateNotificationWithRetryResult createNotificationWithRetry(Defa } } + /** + * Whether a POST /notifications 200 response is the "message sent" branch. + * + *

POST /notifications returns 200 in two cases that share the + * {@link CreateNotificationSuccessResponse} shape: a notification was + * created (non-empty {@code id}), or none was (empty {@code id}, with + * {@code errors} carrying the reason). Prefer this guard over inspecting + * {@code id} directly. + * + * @param response a create-notification success response + * @return {@code true} when a notification was created + */ + public static boolean isMessageSent(CreateNotificationSuccessResponse response) { + return response != null && response.getId() != null && !response.getId().isEmpty(); + } + + /** + * Whether a POST /notifications 200 response is the "message not sent" + * branch -- no notification was created ({@code id} absent or empty); + * inspect {@code errors} for why. + * + * @param response a create-notification success response + * @return {@code true} when no notification was created + */ + public static boolean isMessageNotSent(CreateNotificationSuccessResponse response) { + return !isMessageSent(response); + } + private static String headerValue(Map> headers, String name) { if (headers == null) { return null; diff --git a/src/main/java/com/onesignal/client/api/DefaultApi.java b/src/main/java/com/onesignal/client/api/DefaultApi.java index d7454b8..b195c4e 100644 --- a/src/main/java/com/onesignal/client/api/DefaultApi.java +++ b/src/main/java/com/onesignal/client/api/DefaultApi.java @@ -4069,6 +4069,7 @@ public okhttp3.Call getNotificationHistoryAsync(String notificationId, GetNotifi * @param limit How many notifications to return. Max is 50. Default is 50. (optional) * @param offset Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. (optional) * @param kind Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only (optional) + * @param timeOffset Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. (optional) * @param _callback Callback for upload/download progress * @return Call to execute * @throws ApiException If fail to serialize the request body object @@ -4080,7 +4081,7 @@ public okhttp3.Call getNotificationHistoryAsync(String notificationId, GetNotifi 429 Rate Limit Exceeded - */ - public okhttp3.Call getNotificationsCall(String appId, Integer limit, Integer offset, Integer kind, final ApiCallback _callback) throws ApiException { + public okhttp3.Call getNotificationsCall(String appId, Integer limit, Integer offset, Integer kind, String timeOffset, final ApiCallback _callback) throws ApiException { String basePath = null; // Operation Servers String[] localBasePaths = new String[] { }; @@ -4124,6 +4125,10 @@ public okhttp3.Call getNotificationsCall(String appId, Integer limit, Integer of localVarQueryParams.addAll(localVarApiClient.parameterToPair("kind", kind)); } + if (timeOffset != null) { + localVarQueryParams.addAll(localVarApiClient.parameterToPair("time_offset", timeOffset)); + } + final String[] localVarAccepts = { "application/json" }; @@ -4145,7 +4150,7 @@ public okhttp3.Call getNotificationsCall(String appId, Integer limit, Integer of } @SuppressWarnings("rawtypes") - private okhttp3.Call getNotificationsValidateBeforeCall(String appId, Integer limit, Integer offset, Integer kind, final ApiCallback _callback) throws ApiException { + private okhttp3.Call getNotificationsValidateBeforeCall(String appId, Integer limit, Integer offset, Integer kind, String timeOffset, final ApiCallback _callback) throws ApiException { // verify the required parameter 'appId' is set if (appId == null) { @@ -4153,7 +4158,7 @@ private okhttp3.Call getNotificationsValidateBeforeCall(String appId, Integer li } - okhttp3.Call localVarCall = getNotificationsCall(appId, limit, offset, kind, _callback); + okhttp3.Call localVarCall = getNotificationsCall(appId, limit, offset, kind, timeOffset, _callback); return localVarCall; } @@ -4165,6 +4170,7 @@ private okhttp3.Call getNotificationsValidateBeforeCall(String appId, Integer li * @param limit How many notifications to return. Max is 50. Default is 50. (optional) * @param offset Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. (optional) * @param kind Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only (optional) + * @param timeOffset Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. (optional) * @return NotificationSlice * @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body * @http.response.details @@ -4175,8 +4181,8 @@ private okhttp3.Call getNotificationsValidateBeforeCall(String appId, Integer li 429 Rate Limit Exceeded - */ - public NotificationSlice getNotifications(String appId, Integer limit, Integer offset, Integer kind) throws ApiException { - ApiResponse localVarResp = getNotificationsWithHttpInfo(appId, limit, offset, kind); + public NotificationSlice getNotifications(String appId, Integer limit, Integer offset, Integer kind, String timeOffset) throws ApiException { + ApiResponse localVarResp = getNotificationsWithHttpInfo(appId, limit, offset, kind, timeOffset); return localVarResp.getData(); } @@ -4187,6 +4193,7 @@ public NotificationSlice getNotifications(String appId, Integer limit, Integer o * @param limit How many notifications to return. Max is 50. Default is 50. (optional) * @param offset Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. (optional) * @param kind Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only (optional) + * @param timeOffset Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. (optional) * @return ApiResponse<NotificationSlice> * @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body * @http.response.details @@ -4197,8 +4204,8 @@ public NotificationSlice getNotifications(String appId, Integer limit, Integer o 429 Rate Limit Exceeded - */ - public ApiResponse getNotificationsWithHttpInfo(String appId, Integer limit, Integer offset, Integer kind) throws ApiException { - okhttp3.Call localVarCall = getNotificationsValidateBeforeCall(appId, limit, offset, kind, null); + public ApiResponse getNotificationsWithHttpInfo(String appId, Integer limit, Integer offset, Integer kind, String timeOffset) throws ApiException { + okhttp3.Call localVarCall = getNotificationsValidateBeforeCall(appId, limit, offset, kind, timeOffset, null); Type localVarReturnType = new TypeToken(){}.getType(); return localVarApiClient.execute(localVarCall, localVarReturnType); } @@ -4210,6 +4217,7 @@ public ApiResponse getNotificationsWithHttpInfo(String appId, * @param limit How many notifications to return. Max is 50. Default is 50. (optional) * @param offset Page offset. Default is 0. Results are sorted by queued_at in descending order. queued_at is a representation of the time that the notification was queued at. (optional) * @param kind Kind of notifications returned: * unset - All notification types (default) * `0` - Dashboard only * `1` - API only * `3` - Automated only (optional) + * @param timeOffset Time-offset pagination cursor for sequential pulls of all messages. Accepts either an ISO 8601 formatted timestamp (e.g. `2025-01-01T00:00:00.000Z`) or the opaque Base64 cursor token returned as `next_time_offset` in a prior response. When set, results are sorted ascending by send_after and the standard `offset` parameter cannot be used. Repeat the request with each `next_time_offset` until an empty notifications array is returned. (optional) * @param _callback The callback to be executed when the API call finishes * @return The request call * @throws ApiException If fail to process the API call, e.g. serializing the request body object @@ -4221,9 +4229,9 @@ public ApiResponse getNotificationsWithHttpInfo(String appId, 429 Rate Limit Exceeded - */ - public okhttp3.Call getNotificationsAsync(String appId, Integer limit, Integer offset, Integer kind, final ApiCallback _callback) throws ApiException { + public okhttp3.Call getNotificationsAsync(String appId, Integer limit, Integer offset, Integer kind, String timeOffset, final ApiCallback _callback) throws ApiException { - okhttp3.Call localVarCall = getNotificationsValidateBeforeCall(appId, limit, offset, kind, _callback); + okhttp3.Call localVarCall = getNotificationsValidateBeforeCall(appId, limit, offset, kind, timeOffset, _callback); Type localVarReturnType = new TypeToken(){}.getType(); localVarApiClient.executeAsync(localVarCall, localVarReturnType, _callback); return localVarCall; diff --git a/src/main/java/com/onesignal/client/model/CreateNotificationSuccessResponse.java b/src/main/java/com/onesignal/client/model/CreateNotificationSuccessResponse.java index 1d080b7..b998e3c 100644 --- a/src/main/java/com/onesignal/client/model/CreateNotificationSuccessResponse.java +++ b/src/main/java/com/onesignal/client/model/CreateNotificationSuccessResponse.java @@ -75,11 +75,11 @@ public CreateNotificationSuccessResponse id(String id) { } /** - * Notification identifier when the request created a notification. An empty string means no notification was created; read `errors` for details (HTTP may still be 200). + * Notification identifier when the request created a notification. An empty string means no notification was created; read `errors` for details (HTTP may still be 200). All OneSignal server SDKs expose message-sent / message-not-sent narrowing helpers (named idiomatically per language — e.g. `isMessageSent`, `is_message_sent`, `message_sent?`); prefer them over comparing `id` directly. * @return id **/ @javax.annotation.Nullable - @ApiModelProperty(value = "Notification identifier when the request created a notification. An empty string means no notification was created; read `errors` for details (HTTP may still be 200).") + @ApiModelProperty(value = "Notification identifier when the request created a notification. An empty string means no notification was created; read `errors` for details (HTTP may still be 200). All OneSignal server SDKs expose message-sent / message-not-sent narrowing helpers (named idiomatically per language — e.g. `isMessageSent`, `is_message_sent`, `message_sent?`); prefer them over comparing `id` directly.") public String getId() { return id; diff --git a/src/main/java/com/onesignal/client/model/NotificationSlice.java b/src/main/java/com/onesignal/client/model/NotificationSlice.java index 18462a1..e8d6e91 100644 --- a/src/main/java/com/onesignal/client/model/NotificationSlice.java +++ b/src/main/java/com/onesignal/client/model/NotificationSlice.java @@ -67,6 +67,14 @@ public class NotificationSlice { @SerializedName(SERIALIZED_NAME_LIMIT) private Integer limit; + public static final String SERIALIZED_NAME_TIME_OFFSET = "time_offset"; + @SerializedName(SERIALIZED_NAME_TIME_OFFSET) + private String timeOffset; + + public static final String SERIALIZED_NAME_NEXT_TIME_OFFSET = "next_time_offset"; + @SerializedName(SERIALIZED_NAME_NEXT_TIME_OFFSET) + private String nextTimeOffset; + public static final String SERIALIZED_NAME_NOTIFICATIONS = "notifications"; @SerializedName(SERIALIZED_NAME_NOTIFICATIONS) private List notifications = null; @@ -143,6 +151,52 @@ public void setLimit(Integer limit) { } + public NotificationSlice timeOffset(String timeOffset) { + + this.timeOffset = timeOffset; + return this; + } + + /** + * The time_offset cursor specified in the request, if any. + * @return timeOffset + **/ + @javax.annotation.Nullable + @ApiModelProperty(value = "The time_offset cursor specified in the request, if any.") + + public String getTimeOffset() { + return timeOffset; + } + + + public void setTimeOffset(String timeOffset) { + this.timeOffset = timeOffset; + } + + + public NotificationSlice nextTimeOffset(String nextTimeOffset) { + + this.nextTimeOffset = nextTimeOffset; + return this; + } + + /** + * An opaque Base64 cursor token representing the next page of messages to fetch. Present when time_offset was provided in the request. Pass this value as time_offset on the next request to continue paginating. + * @return nextTimeOffset + **/ + @javax.annotation.Nullable + @ApiModelProperty(value = "An opaque Base64 cursor token representing the next page of messages to fetch. Present when time_offset was provided in the request. Pass this value as time_offset on the next request to continue paginating.") + + public String getNextTimeOffset() { + return nextTimeOffset; + } + + + public void setNextTimeOffset(String nextTimeOffset) { + this.nextTimeOffset = nextTimeOffset; + } + + public NotificationSlice notifications(List notifications) { this.notifications = notifications; @@ -187,12 +241,14 @@ public boolean equals(Object o) { return Objects.equals(this.totalCount, notificationSlice.totalCount) && Objects.equals(this.offset, notificationSlice.offset) && Objects.equals(this.limit, notificationSlice.limit) && + Objects.equals(this.timeOffset, notificationSlice.timeOffset) && + Objects.equals(this.nextTimeOffset, notificationSlice.nextTimeOffset) && Objects.equals(this.notifications, notificationSlice.notifications); } @Override public int hashCode() { - return Objects.hash(totalCount, offset, limit, notifications); + return Objects.hash(totalCount, offset, limit, timeOffset, nextTimeOffset, notifications); } @Override @@ -202,6 +258,8 @@ public String toString() { sb.append(" totalCount: ").append(toIndentedString(totalCount)).append("\n"); sb.append(" offset: ").append(toIndentedString(offset)).append("\n"); sb.append(" limit: ").append(toIndentedString(limit)).append("\n"); + sb.append(" timeOffset: ").append(toIndentedString(timeOffset)).append("\n"); + sb.append(" nextTimeOffset: ").append(toIndentedString(nextTimeOffset)).append("\n"); sb.append(" notifications: ").append(toIndentedString(notifications)).append("\n"); sb.append("}"); return sb.toString(); @@ -228,6 +286,8 @@ private String toIndentedString(Object o) { openapiFields.add("total_count"); openapiFields.add("offset"); openapiFields.add("limit"); + openapiFields.add("time_offset"); + openapiFields.add("next_time_offset"); openapiFields.add("notifications"); // a set of required properties/fields (JSON key names)