Push notifications

{
  "teamId": "YOUR_APPLE_TEAM_ID",
  "keyId": "YOUR_APNS_KEY_ID",
  "topic": "com.example.app",
  "environment": "production",
  "privateKey": "-----BEGIN PRIVATE KEY-----\nYOUR_COMPLETE_P8_KEY_CONTENTS\n-----END PRIVATE KEY-----\n"
}

private PushClient push;

public void init(Object context) {
    push = PushClient.builder("cn1_push_application_key")
            .listener(new PushListener() {
                @Override
                public void onRegistration(PushSubscription subscription) {
                    Log.p("Push ready on " + subscription.getTransportId());
                }

                @Override
                public void onMessage(PushMessage message) {
                    if (message.getDeepLink() != null) {
                        Log.p("Route to " + message.getDeepLink());
                    }
                }

                @Override
                public void onError(PushError error) {
                    Log.p(error.getCode() + ": " + error.getMessage());
                }
            })
            .build();
}

public void start() {
    push.register();
}

public void stop() {
    // Keep the subscription and listener active while the app is paused.
}

public void disableNotifications() {
    // Use only for an explicit user opt-out.
    push.unregister();
}

PushMessage message = PushMessage.builder()
        .title("Order shipped")
        .body("Order 4815 is on its way")
        .deepLink("myapp://orders/4815")
        .imageUrl("https://example.com/orders/4815.png")
        .collapseKey("order-4815")
        .ttlSeconds(3600)
        .data("orderId", "4815")
        .build();

{
  "schema": 3,
  "title": "Order shipped",
  "body": "Order 4815 is on its way",
  "deepLink": "myapp://orders/4815",
  "collapseKey": "order-4815",
  "ttl": 3600,
  "data": { "orderId": "4815" },
  "platform": {
    "apns": { "badge": 3, "sound": "default", "interruptionLevel": "time-sensitive" },
    "fcm": { "channelId": "orders", "priority": "high" },
    "huawei": { "channelId": "orders", "importance": "HIGH" },
    "wns": { "type": "toast" },
    "web": { "urgency": "high" }
  }
}

curl -X POST https://cloud.codenameone.com/api/v3/push/messages \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "APPLICATION_ID",
    "targets": [
      {"provider":"fcm", "token":"OPAQUE_DEVICE_TOKEN"},
      {"provider":"apns", "token":"OPAQUE_DEVICE_TOKEN"}
    ],
    "message": {
      "schema":3,
      "title":"Order shipped",
      "body":"Order 4815 is on its way",
      "data":{"orderId":"4815"}
    }
  }'

{
  "appId": "YOUR_APPLICATION_UUID",
  "targets": [
    {"provider": "fcm", "token": "cn1-fcm-YOUR_ANDROID_DEVICE_TOKEN"},
    {"provider": "apns", "token": "cn1-ios-YOUR_IOS_DEVICE_TOKEN"}
  ],
  "message": {
    "schema": 3,
    "classic": {"type": 1, "body": "Hello"}
  }
}

{
  "version": 1,
  "organization": "9f1c2f7a-2f6e-4a5b-9d71-3f0a7c1d5e22",
  "generatedAt": 1790179200000,
  "window": {"from": 1790092800000, "to": 1790179200000},
  "summary": {
    "fcm":  {"ACCEPTED": 7412, "FAILED": 1},
    "apns": {"ACCEPTED": 3310},
    "web":  {"DEAD": 1}
  },
  "events": [
    {
      "deliveryId": "6f0f6f1e-9a1e-4f2a-9a7a-6d5f5f6a1b02",
      "device": "cn1-fcm-fH9c...Qk",
      "token": "fH9c...Qk",
      "provider": "fcm",
      "status": "FAILED",
      "reason": "INVALID_TARGET",
      "attempts": 1,
      "at": 1790178322418,
      "detail": "{\"error\":{\"code\":404,\"status\":\"NOT_FOUND\"}}"
    },
    {
      "deliveryId": "d2b1a0c4-1f77-4a4d-9d0e-2c5b7a91f3aa",
      "device": "cn1-web-https://push.example.com/sub/9?p256dh=KEY&auth=AUTH",
      "endpoint": "https://push.example.com/sub/9",
      "provider": "web",
      "status": "DEAD",
      "reason": "TRANSIENT_FAILURE",
      "attempts": 6,
      "at": 1790178901004,
      "detail": "gave up after repeated 503 responses"
    }
  ],
  "truncated": false,
  "eventsOmitted": 10722
}

@RestController
@RequestMapping("/push")
public class PushFeedback {

    /**
     * Your organization-scoped durable store. Store provider and bare token (or
     * web endpoint) alongside the original push key; backfill existing rows before
     * enabling cleanup. Both operations belong in ONE transaction: a marker
     * written before the deletion commits turns a retry into a silent skip,
     * and a deletion without a marker is applied twice.
     */
    public interface DeviceStore {
        boolean alreadyApplied(String eventKey);

        // provider + target match normalized registration columns, NOT Push.getPushKey().
        // Enforce a unique eventKey and delete in the same transaction.
        void removeTargetAndMarkApplied(String eventKey, String provider, String target)
                throws Exception;
    }

    /** Assigned once at start-up; there is no dependency injection here. */
    static DeviceStore store;

    /** The signing secret shown in Push > Settings. Read it from configuration. */
    private static final String SECRET = System.getenv("CN1_PUSH_CALLBACK_SECRET");

    /** Reject a digest whose timestamp is older than this, to bound replay. */
    private static final long MAX_AGE_MS = 5 * 60 * 1000L;

    @PostMapping("/feedback")
    public HttpServer.Response feedback(HttpServer.Request request) throws Exception {
        String body = request.getBody();
        if (!verified(request.getHeader("X-CN1-Signature"), body)) {
            // Anything but 2xx keeps the window at the sender and resends it,
            // which is what you want while a secret rotation is half-applied.
            return new HttpServer.Response(401, "text/plain",
                    "bad signature".getBytes(StandardCharsets.UTF_8));
        }
        Map digest = JSONParser.parseJSON(body);
        List events = (List) digest.get("events");
        if (events != null) {
            for (Object entry : events) {
                Map event = (Map) entry;
                if (!"INVALID_TARGET".equals(event.get("reason"))) {
                    continue;
                }
                String provider = (String) event.get("provider");
                String target = (String) event.get("token");
                if (target == null || target.length() == 0) {
                    target = (String) event.get("endpoint");
                }
                if (provider == null || provider.length() == 0
                        || target == null || target.length() == 0) {
                    throw new IllegalArgumentException("Missing push target");
                }
                String deliveryId = (String) event.get("deliveryId");
                String eventKey;
                if (deliveryId != null && deliveryId.length() > 0) {
                    eventKey = "delivery:" + deliveryId;
                } else {
                    Object at = event.get("at");
                    if (at == null) {
                        throw new IllegalArgumentException("Missing classic event timestamp");
                    }
                    eventKey = "classic:" + provider + ":" + target.length()
                            + ":" + target + ":" + at;
                }
                if (!store.alreadyApplied(eventKey)) {
                    store.removeTargetAndMarkApplied(eventKey, provider, target);
                }
            }
        }
        // 2xx acknowledges that this window is durably applied: it advances the
        // sender's watermark and the window is never sent again. Answer it
        // after the writes above have committed, not alongside them.
        return new HttpServer.Response(200, "text/plain",
                "ok".getBytes(StandardCharsets.UTF_8));
    }

    // throws, because String.getBytes(Charset) is a CHECKED throw in the
    // ParparVM class library even though it is not one on a JVM.
    private static boolean verified(String header, String body) throws Exception {
        if (header == null || SECRET == null) {
            return false;
        }
        long timestamp = 0;
        String provided = null;
        // Parsed by hand: java.lang.String has no split() in the ParparVM class
        // library, so the obvious version of this compiles for the development
        // run and fails the native package step.
        int cursor = 0;
        while (cursor < header.length()) {
            int comma = header.indexOf(',', cursor);
            if (comma < 0) {
                comma = header.length();
            }
            String part = header.substring(cursor, comma);
            cursor = comma + 1;
            int equals = part.indexOf('=');
            if (equals < 1) {
                continue;
            }
            String name = part.substring(0, equals).trim();
            String value = part.substring(equals + 1).trim();
            if ("t".equals(name)) {
                timestamp = Long.parseLong(value);
            } else if ("v1".equals(name)) {
                provided = value;
            }
        }
        if (provided == null
                || Math.abs(System.currentTimeMillis() - timestamp) > MAX_AGE_MS) {
            return false;
        }
        // Crypto, not javax.crypto: this class is recompiled against the
        // ParparVM class library by cn1:backend-package, and that library has
        // no JCE. equalsConstantTime is here for the same reason a hand-written
        // loop would be -- an early exit on the first differing byte lets a MAC
        // be forged one byte at a time.
        byte[] expected = Crypto.hmacSha256(SECRET.getBytes(StandardCharsets.UTF_8),
                (timestamp + "." + body).getBytes(StandardCharsets.UTF_8));
        return Crypto.equalsConstantTime(expected, decodeHex(provided));
    }

    private static byte[] decodeHex(String value) {
        if (value.length() % 2 != 0) {
            return new byte[0];
        }
        byte[] out = new byte[value.length() / 2];
        for (int i = 0; i < out.length; i++) {
            int high = Character.digit(value.charAt(i * 2), 16);
            int low = Character.digit(value.charAt(i * 2 + 1), 16);
            if (high < 0 || low < 0) {
                return new byte[0];
            }
            out[i] = (byte) ((high << 4) | low);
        }
        return out;
    }
}

// Express. Verify before any JSON middleware touches the body: the signature
// covers the bytes we sent, and express.json() hands you an object whose
// re-serialisation is not byte-identical, so it never verifies.
const express = require('express');
const crypto = require('crypto');

const app = express();
const SECRET = process.env.CN1_PUSH_CALLBACK_SECRET;
const MAX_AGE_MS = 5 * 60 * 1000;

function verifySignature(header, body) {
  const parts = Object.fromEntries((header || '').split(',')
      .map(p => [p.slice(0, p.indexOf('=')).trim(), p.slice(p.indexOf('=') + 1).trim()]));
  const expected = Buffer.from(
      crypto.createHmac('sha256', SECRET).update(`${parts.t}.${body}`).digest('hex'), 'utf8');
  const provided = Buffer.from(parts.v1 || '', 'utf8');
  return expected.length === provided.length
      && crypto.timingSafeEqual(expected, provided)
      && Math.abs(Date.now() - Number(parts.t)) <= MAX_AGE_MS;
}

// Store provider + bare token/web endpoint alongside the original push key.
// Backfill existing registrations before enabling cleanup. The durable store
// is scoped to this endpoint's organization.
function cleanupTarget(event) {
  const provider = event.provider;
  const target = event.token || event.endpoint;
  if (typeof provider !== 'string' || !provider
      || typeof target !== 'string' || !target) {
    throw new Error('Missing push target');
  }
  let eventKey;
  if (typeof event.deliveryId === 'string' && event.deliveryId) {
    eventKey = `delivery:${event.deliveryId}`;
  } else {
    if (!Number.isSafeInteger(event.at)) {
      throw new Error('Missing classic event timestamp');
    }
    eventKey = `classic:${provider}:${target.length}:${target}:${event.at}`;
  }
  return {eventKey, provider, target};
}

app.post('/push/feedback', express.raw({type: 'application/json'}), async (req, res) => {
  const body = req.body.toString('utf8');
  if (!verifySignature(req.get('X-CN1-Signature'), body)) {
    return res.sendStatus(401);       // not 2xx, so the same window is resent
  }

  try {
    for (const event of JSON.parse(body).events || []) {
      // Digests are at-least-once, so the deduplication marker and the
      // deletion have to commit together: a marker stored first turns a retry
      // into a silent skip, and a deletion without one is applied twice.
      if (event.reason === 'INVALID_TARGET') {
        const {eventKey, provider, target} = cleanupTarget(event);
        // Enforce eventKey uniqueness and commit marker + removal together.
        await removeTargetIfNotApplied(eventKey, provider, target);
      }
    }
  } catch (failure) {
    // Let it be resent rather than acknowledging work that did not land.
    return res.sendStatus(500);
  }

  // 2xx only now: it advances our watermark and this window is never sent again.
  res.sendStatus(200);
});

// A serverless function behind an HTTP gateway. Two things differ from a
// long-lived server, and both are silent when they are wrong.
const crypto = require('crypto');

const SECRET = process.env.CN1_PUSH_CALLBACK_SECRET;
const MAX_AGE_MS = 5 * 60 * 1000;

function verifySignature(header, body) {
  const parts = Object.fromEntries((header || '').split(',')
      .map(p => [p.slice(0, p.indexOf('=')).trim(), p.slice(p.indexOf('=') + 1).trim()]));
  const expected = Buffer.from(
      crypto.createHmac('sha256', SECRET).update(`${parts.t}.${body}`).digest('hex'), 'utf8');
  const provided = Buffer.from(parts.v1 || '', 'utf8');
  return expected.length === provided.length
      && crypto.timingSafeEqual(expected, provided)
      && Math.abs(Date.now() - Number(parts.t)) <= MAX_AGE_MS;
}

exports.handler = async (event) => {
  // 1. The gateway may hand you the body base64-encoded, and it decides that
  //    by sniffing content rather than by anything you control. Hashing the
  //    encoded form verifies nothing and fails closed on every digest.
  const body = event.isBase64Encoded
      ? Buffer.from(event.body, 'base64').toString('utf8')
      : event.body;

  // Header names arrive lower-cased from some gateways and not from others.
  const headers = event.headers || {};
  const signature = headers['x-cn1-signature'] || headers['X-CN1-Signature'];
  if (!verifySignature(signature, body)) {
    return {statusCode: 401, body: 'bad signature'};
  }

  // 2. There is no process to keep state in, so deduplication and the device
  //    table both have to be the database. A warm container that remembers
  //    delivery ids is an optimisation, never the correctness mechanism.
  // applyDurably must use the same provider + target normalization and
  // deliveryId/classic-event fallback as the long-running receiver above.
  await applyDurably(JSON.parse(body).events || []);

  // Return after the writes, not alongside them: a function that answers 200
  // and is frozen before its writes flush has told us to advance the watermark
  // over a window nobody stored.
  return {statusCode: 200, body: 'ok'};
};

@RestController
public class PushFeedbackSpring {

    private static final long MAX_AGE_MS = 5 * 60 * 1000L;

    // An injected collaborator, NOT a method on this class. Spring's
    // transaction management is proxy-based, so a call from one method of this
    // bean to another of its own never passes through the interceptor, and a
    // @Transactional there would do nothing at all -- without saying so.
    private final PushFeedbackApplier applier;
    private final byte[] secret;

    public PushFeedbackSpring(PushFeedbackApplier applier,
            @Value("${cn1.push.callback.secret}") String secret) {
        this.applier = applier;
        this.secret = secret.getBytes(StandardCharsets.UTF_8);
    }

    // byte[], not a mapped type: the signature covers the bytes as sent, and
    // anything Jackson parses and re-serialises is a different byte string that
    // never verifies.
    @PostMapping(path = "/push/feedback", consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<String> feedback(
            @RequestHeader(name = "X-CN1-Signature", required = false) String signature,
            @RequestBody byte[] raw) throws Exception {
        String body = new String(raw, StandardCharsets.UTF_8);
        if (!verified(signature, body, secret)) {
            // Anything but 2xx keeps the window at the sender and resends it.
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("bad signature");
        }
        JsonNode digest = new ObjectMapper().readTree(body);
        for (JsonNode event : digest.path("events")) {
            applier.apply(event);
        }
        // 2xx advances the sender's watermark, so it is returned only after
        // every event above has committed.
        return ResponseEntity.ok("ok");
    }

    static boolean verified(String header, String body, byte[] secret) throws Exception {
        if (header == null) {
            return false;
        }
        long timestamp = 0;
        String provided = null;
        for (String part : header.split(",")) {
            int equals = part.indexOf('=');
            if (equals < 1) {
                continue;
            }
            String name = part.substring(0, equals).trim();
            String value = part.substring(equals + 1).trim();
            if ("t".equals(name)) {
                timestamp = Long.parseLong(value);
            } else if ("v1".equals(name)) {
                provided = value;
            }
        }
        if (provided == null
                || Math.abs(System.currentTimeMillis() - timestamp) > MAX_AGE_MS) {
            return false;                      // bound replay by age
        }
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret, "HmacSHA256"));
        byte[] expected = mac.doFinal(
                (timestamp + "." + body).getBytes(StandardCharsets.UTF_8));
        // MessageDigest.isEqual is the JDK's constant-time comparison. Never
        // Arrays.equals or String.equals here: both return at the first
        // differing byte, and that timing is enough to forge a signature.
        return MessageDigest.isEqual(expected, HexFormat.of().parseHex(provided));
    }
}

@Component
class PushFeedbackApplier {

    private final DeviceStore store;

    PushFeedbackApplier(DeviceStore store) {
        this.store = store;
    }

    /**
     * One transaction per event: the deduplication marker and the deletion have
     * to commit together. A marker written first turns a retry into a silent
     * skip; a deletion without one is applied twice.
     */
    @Transactional
    public void apply(JsonNode event) {
        if (!"INVALID_TARGET".equals(event.path("reason").asText(null))) {
            return;
        }
        String provider = event.path("provider").asText(null);
        String target = event.path("token").asText(null);
        if (target == null || target.isEmpty()) {
            target = event.path("endpoint").asText(null);
        }
        if (provider == null || provider.isEmpty() || target == null || target.isEmpty()) {
            throw new IllegalArgumentException("Missing push target");
        }
        String deliveryId = event.path("deliveryId").asText(null);
        String eventKey;
        if (deliveryId != null && !deliveryId.isEmpty()) {
            eventKey = "delivery:" + deliveryId;
        } else {
            String at = event.path("at").asText(null);
            if (at == null) {
                throw new IllegalArgumentException("Missing classic event timestamp");
            }
            eventKey = "classic:" + provider + ":" + target.length() + ":" + target + ":" + at;
        }
        if (store.alreadyApplied(eventKey)) {
            return;
        }
        store.removeTarget(provider, target);
        store.markApplied(eventKey);
    }
}

@Path("/push")
@ApplicationScoped
public class PushFeedbackMicroProfile {

    // Injected, not a method on this bean: CDI interceptors are proxy-based
    // exactly like Spring's, so this.apply(...) would never reach the
    // @Transactional interceptor and the guarantee would be silently absent.
    @Inject
    PushFeedbackCdiApplier applier;

    // MicroProfile Config, so the secret arrives the same way as every other
    // deployment value rather than as a constant in the source.
    @Inject
    @ConfigProperty(name = "cn1.push.callback.secret")
    String secret;

    // byte[] entity, for the reason it is byte[] everywhere else: a provider
    // that binds this to a POJO reads the bytes, and the re-serialised form no
    // longer matches the signature.
    @POST
    @Path("/feedback")
    @Consumes(MediaType.APPLICATION_JSON)
    public Response feedback(@HeaderParam("X-CN1-Signature") String signature, byte[] raw)
            throws Exception {
        String body = new String(raw, StandardCharsets.UTF_8);
        // The verification is protocol, not framework: HMAC-SHA256 over
        // "<t>.<raw body>", constant-time compare, timestamp inside the window.
        if (!PushFeedbackSpring.verified(signature, body,
                secret.getBytes(StandardCharsets.UTF_8))) {
            return Response.status(Response.Status.UNAUTHORIZED).entity("bad signature").build();
        }
        try (JsonReader reader = Json.createReader(new StringReader(body))) {
            JsonObject digest = reader.readObject();
            JsonValue events = digest.get("events");
            if (events != null) {
                for (JsonValue value : events.asJsonArray()) {
                    applier.apply(value.asJsonObject());
                }
            }
        }
        return Response.ok("ok").build();
    }
}

@ApplicationScoped
class PushFeedbackCdiApplier {

    @Inject
    DeviceStore store;

    /** Marker and deletion in one transaction, as in the Spring receiver. */
    @Transactional
    public void apply(JsonObject event) {
        if (!"INVALID_TARGET".equals(event.getString("reason", null))) {
            return;
        }
        String provider = event.getString("provider", null);
        String target = event.getString("token", null);
        if (target == null || target.isEmpty()) {
            target = event.getString("endpoint", null);
        }
        if (provider == null || provider.isEmpty() || target == null || target.isEmpty()) {
            throw new IllegalArgumentException("Missing push target");
        }
        String deliveryId = event.getString("deliveryId", null);
        String eventKey;
        if (deliveryId != null && !deliveryId.isEmpty()) {
            eventKey = "delivery:" + deliveryId;
        } else {
            String at = (event.get("at") == null ? null : event.get("at").toString());
            if (at == null) {
                throw new IllegalArgumentException("Missing classic event timestamp");
            }
            eventKey = "classic:" + provider + ":" + target.length() + ":" + target + ":" + at;
        }
        if (store.alreadyApplied(eventKey)) {
            return;
        }
        store.removeTarget(provider, target);
        store.markApplied(eventKey);
    }
}

{
  "externalUserId": "customer-4815",
  "tags": {
    "subscription": "active",
    "region": "emea",
    "testUser": "false"
  }
}

{
  "enabled": true,
  "trigger": {"event": "order.ready"},
  "delaySeconds": 0,
  "message": {
    "schema": 3,
    "title": "Order update",
    "body": "Order ${event.orderId} is ready"
  }
}

{
  "name": "order.ready",
  "externalUserId": "customer-4815",
  "properties": {"orderId": "4815"}
}

{
  "schema": 3,
  "silent": true,
  "surface": {
    "operation": "widget",
    "kind": "order-status",
    "timeline": "{...serialized widget timeline...}"
  }
}

// companyTransport is supplied by the native CN1Lib.
// listener is the application's normal, non-null PushListener.
PushClient client = PushClient.builder("private-app-id")
        .transport(companyTransport)
        .registrationSink(new PushRegistrationSink() {
            @Override
            public void registered(PushSubscription value) {
                Log.p("Send the subscription to the company server");
            }

            @Override
            public void unregistered(PushSubscription value) {
                Log.p("Remove the subscription from the company server");
            }
        })
        .listener(listener)
        .build();