Notifications and push delivery

​

Trainee push

​

The one entry point

const notifier = createTraineeNotifier({ prisma: ctx.prisma, logger: ctx.logger });

await notifier.notify(studioId, 'TRAINING_PLAN_ASSIGNED', [{ clientId, vars: { plan: 'Hypertrophy A' } }]);
const result = await notifier.send(studioId, 'TRAINER_MESSAGE', [{ clientId, bodyOverride: text }]);

• notify returns the number of messages Expo accepted. Use it for fire and forget sends.
• send returns the full TraineePushResult for callers that report delivery back to a coach.

​

Notification types

​

Configuration layers

1. StudioNotificationConfig for this studio and type (the studio’s own setting).
2. NotificationTypeConfig for the type (platform default, managed through /v1/admin/notification-configs).
3. NOTIFICATION_CONFIG_DEFAULTS in code.

export type EffectiveNotificationConfig = {
  enabled: boolean;
  titleTemplate: string;
  bodyTemplate: string;
  sound: boolean;
  sendTime: string | null;
  messages: NotificationMessage[];
};

​

What sendTraineeNotification does

​

Recipient options

export type TraineePushRecipient = {
  clientId: string;
  formType?: string;
  message?: { title: string; subtitle: string };
  target?: string;
  vars?: Record<string, string>;
  data?: Record<string, unknown>;
  bodyOverride?: string;
};

​

The message sent to Expo

​

The result

export type TraineePushResult = {
  accepted: number;   // messages Expo queued
  devices: number;    // devices addressed
  reached: string[];  // clientIds Expo queued a message for
  noDevice: string[]; // clientIds with no registered token
  muted: string[];    // clientIds who muted this group
  skipped: string[];  // no usable template for this recipient
  disabled: boolean;  // type is off for the studio
};

​

Tickets are not delivery

1. After a send, schedulePushReceipts(entries) hands the accepted tickets to the scheduler installed at boot.
2. installPushReceipts enqueues them on push-receipt-check in chunks of 300 with a 15 minute delay, Expo’s own guidance for when receipts are ready.
3. The worker calls applyPushReceipts, which fetches receipts and builds a summary: delivered, failed, pending, an error histogram, counts by platform and up to five sample messages.
4. Tokens with a DeviceNotRegistered receipt are pruned.
5. A failure is logged at error as trainee push: deliveries failed after Expo accepted them. Success is logged as trainee push: receipts confirmed.

​

Device tokens

​

Trainee preferences

​

Where pushes are triggered

​

Debugging a missing push

1. trainee push: type disabled for this studio: the studio switched the type off.
2. trainee push: no registered devices, nothing sent: the app is not installed, the trainee signed out, or the token was pruned.
3. trainee push: every reachable recipient muted this type: the trainee muted the group.
4. expo push: ticket error with a code: Expo refused the message.
5. trainee push: sent with accepted above zero: Expo took it. Wait 15 minutes.
6. trainee push: deliveries failed after Expo accepted them: a credential problem. Read byPlatform and samples.

​

Coach notifications

await createNotification({
  userId,
  type: 'APP_UPDATE',
  data: { title: 'New feature', message: '...' },
  link: '/settings',
});

1. Checks the user’s preferences for the type on two targets, IN_APP and EMAIL (isNotificationDisabled).
2. Resolves link to an absolute web app URL with resolveNotificationLink.
3. Inserts the row unless in-app is disabled.
4. Sends the notification email template unless email is disabled, in the user’s stored locale. The email title is data.headline, else data.title, else the type name.