feat(node): read an email's status with emails.get

.changeset/core-request-json.md

@@ -0,0 +1,5 @@
+---
+'@posthog/core': patch
+---
+
+Let SDKs built on core send JSON requests to the PostHog API through the shared retrying transport.

.changeset/node-emails-code-fields.md

@@ -0,0 +1,5 @@
+---
+'posthog-node': minor
+---
+
+The code form of `posthog.emails.send()` takes `cc`, `bcc`, `headers`, `tags` and `attachments`. An attachment's `content` is a Buffer, a Uint8Array or a Base64 string. A Resend attachment with a `path` returns an `invalid_attachment` error, because PostHog can't fetch files. A PostHog server that doesn't take one of these fields yet refuses the send with an `invalid_request` error on that field, instead of sending without it.

.changeset/node-emails-code-form.md

@@ -0,0 +1,5 @@
+---
+'posthog-node': minor
+---
+
+`posthog.emails.send()` also sends email content from your code, named by a `templateKey`: rendered content as is, or a local template that PostHog fills with `templateData`. The SDK uploads a local template on its first send and whenever its content changes. Template sends by id move to the same send route, with no change for callers.

.changeset/node-emails-get.md

@@ -0,0 +1,5 @@
+---
+'posthog-node': minor
+---
+
+Add `posthog.emails.get(id)` to read the latest status of an email that `posthog.emails.send()` queued.

.changeset/node-emails-send.md

@@ -0,0 +1,5 @@
+---
+'posthog-node': minor
+---
+
+Add `posthog.emails.send()` to send transactional email from a template made in PostHog, by its id. Every send carries an idempotency key and retries network errors, throttling and an unavailable pipeline with the same key. Results are `{ data, error }`, with Resend's error names. New client options: `appHost`, `maxRetries` and `migratedFrom`.

packages/core/src/posthog-core-stateless.ts

@@ -17,6 +17,7 @@ import {
   PostHogFeatureFlagDetails,
   FeatureFlagDetail,
   SurveyResponse,
+  PostHogApiResponse,
   PostHogFetchResponse,
   PostHogFetchBodyBytes,
   PostHogFetchOptions,
@@ -40,6 +41,7 @@ import {
   createLogger,
   getEventUuid,
   safeJsonStringify,
+  trySafe,
 } from './utils'
 import { parseRetryAfterMs } from './utils/retry-after'
 import { uuidv7 } from './vendor/uuidv7'
@@ -156,6 +158,11 @@ type SuccessfulWriteResponseHandling = {
   type: 'successful-write'
 }
 
+async function readApiResponse(response: PostHogFetchResponse): Promise<PostHogApiResponse> {
+  const text = await response.text()
+  return { status: response.status, body: trySafe(() => JSON.parse(text)) }
+}
+
 export const maybeAdd = (key: string, value: JsonType | undefined): Record<string, JsonType> =>
   value !== undefined ? { [key]: value } : {}
 
@@ -1874,6 +1881,25 @@ export abstract class PostHogCoreStateless {
     return this._sendOtlpBatch({ path: 'traces', auth: 'bearer', payload })
   }
 
+  protected async requestJson(
+    url: string,
+    options: PostHogFetchOptions,
+    retryOptions?: Partial<RetriableOptions>
+  ): Promise<PostHogApiResponse> {
+    try {
+      return await this.fetchWithRetry(url, options, { type: 'required', consume: readApiResponse }, retryOptions)
+    } catch (error) {
+      if (error instanceof PostHogFetchHttpError) {
+        return {
+          status: error.status,
+          body: await error.json.catch(() => undefined),
+          retryAfterMs: error.retryAfterMs,
+        }
+      }
+      throw error
+    }
+  }
+
   private fetchWithRetry<T>(
     url: string,
     options: PostHogFetchOptions,

packages/core/src/types.ts

@@ -336,6 +336,13 @@ export type PostHogFetchResponse = {
   body?: ReadableStream<Uint8Array> | null
 }
 
+export type PostHogApiResponse = {
+  status: number
+  body: unknown
+  /** The answer's `Retry-After` in milliseconds, when it sent a usable one. */
+  retryAfterMs?: number
+}
+
 export type PostHogQueueItem = {
   message?: PostHogEventProperties
   callback?: (err: unknown) => void