'errors' property is `any`, makes the typing useless

[jpike88]

I don't know why for such a critical property, it's just been given a type of 'any'. Is it always an array of strings? How is this acceptable?

onesignal-node-api/models/CreateNotificationSuccessResponse.ts

Line 17 in 0d5de91

'errors'?: any;

[sherwinski]

Hey @jpike88,

Thanks for the feedback here -- you're right that we can provide more information on errors per endpoint. I've made a note to investigate the different errors we can return and work this type towards something more precise.

[matheusfaggi]

In addition, returning the response with id?: string is really bad

[sherwinski]

I'm looking into how to improve the types against the different error variants that the API returns, e.g. successful notifications with invalid targets, successful notifications with no subscriptions, etc. Will follow-up with updates here.

[sherwinski]

We're making some updates to error handling that should hopefully help here. It still hasn't landed in main yet but once it gets staged, I'll follow up with some more information.

[sherwinski]

I appreciate everyone's patience on this issue, as it required digging and thoughtful approach from our team. First off, I agree that any is an unsatisfying type to export here. I wanted to start with an explanation as to why we published it with any, and then talk about some updates we've made to hopefully improve the ergonomics of working around this.

Why are errors typed loosely?

POST /notifications returns HTTP 200 in two different shapes that share CreateNotificationSuccessResponse, where errors is polymorphic across them:

• A no-op success (no recipients matched): id is "" and errors is a string[], e.g. ["All included players are not subscribed"].
• A partial success with invalid targets: errors is an object map, e.g. { "invalid_aliases": {...}, "invalid_external_user_ids": [...], "invalid_player_ids": [...] }.

So errors is sometimes an array of strings and sometimes a keyed object — on the same 200 response. Forcing it to string[] would type-check but actively mislead you on the partial-success path. Rather than ship a lossy type, we kept the field permissive and added typed, ergonomic helpers on top of it.

What's new (as of v5.9.0)

1. Narrowing helpers for the two 200 branches, so you never have to compare id === "" by hand:

import { isMessageSent, isMessageNotSent } from '@onesignal/node-onesignal';

const res = await client.createNotification(notification);

if (isMessageSent(res)) {
  // a notification was created; res.id is a non-empty UUID
  console.log('sent', res.id);
} else {
  // isMessageNotSent: nothing was created; res.errors says why
  console.warn('not sent', res.errors);
}

2. ApiException.errorMessages — a normalized accessor that flattens every error-envelope shape the API can return ({ errors: "..." }, { errors: ["..."] }, { errors: [{ code, title }] }, and object maps like { errors: { invalid_aliases: {...} } }) down to a flat string[]. The raw body still lives on .body. This should make it easier to understand why a notification partial/fully failed.

try {
  await client.createNotification(notification);
} catch (e) {
  if (e instanceof ApiException) {
    console.error(e.errorMessages); // always string[]
  }
}

3. OneSignalErrors — a typed catalog of the API's sentinel message strings (e.g. NO_SUBSCRIBERS, NO_TARGETING_SPECIFIED, SERVICE_UNAVAILABLE) so you can test membership instead of hand-matching strings:

import { OneSignalErrors, isMessageNotSent } from '@onesignal/node-onesignal';

if (isMessageNotSent(res) && Array.isArray(res.errors)
    && res.errors.includes(OneSignalErrors.NO_SUBSCRIBERS)) {
  // handle the "no recipients" case specifically
}

4. createNotificationWithRetry — a helper that sets an idempotency key, retries transient 429/503/transport failures with the same key (honoring Retry-After), and tells you whether the server replayed a deduped request (Idempotent-Replayed).

5. Updates to our docs that clarify the id / errors field on CreateNotificationSuccessResponse, explains the polymorphism, and points out the aforementioned helpers.

Longer term we're evaluating modeling the 200 response as a proper discriminated union so errors can be narrowed by the type system directly, but the helpers above are meant to close the practical gap today. Would love to hear if these help with your use case or if there's a situation you're still experiencing friction with.