@automate.ax/integration-contracts 0.161.0 → 0.163.0

package/src/meta-ads/schemas.ts

@@ -190,11 +190,18 @@ export const META_ADS_WEBHOOK_CHANGE_SCHEMA = z.object({
   value: encodableSchema,
 })
 
+/**
+ * Meta's shared Webhooks envelope. Field-change objects use `changes`, while
+ * Messenger and Instagram messaging use `messaging`; validate each messaging
+ * event only after classification so unrelated event kinds never reject the
+ * whole delivery.
+ */
 export const META_ADS_WEBHOOK_ENVELOPE_SCHEMA = z.object({
   entry: z
     .object({
-      changes: META_ADS_WEBHOOK_CHANGE_SCHEMA.array(),
+      changes: META_ADS_WEBHOOK_CHANGE_SCHEMA.array().optional(),
       id: z.string(),
+      messaging: encodableSchema.array().optional(),
       time: z.number(),
     })
     .array(),
@@ -204,3 +211,78 @@ export const META_ADS_WEBHOOK_ENVELOPE_SCHEMA = z.object({
 export type MetaAdsWebhookEnvelope = z.output<
   typeof META_ADS_WEBHOOK_ENVELOPE_SCHEMA
 >
+
+export const META_ADS_PAGE_SCHEMA = metaObject({
+  category: z.string().optional(),
+  id: META_ADS_ID_SCHEMA,
+  name: z.string(),
+  tasks: z.string().array().optional(),
+})
+
+export const META_ADS_INSTAGRAM_ACCOUNT_PAGE_SCHEMA = metaObject({
+  id: META_ADS_ID_SCHEMA,
+  instagramBusinessAccount: metaObject({
+    id: META_ADS_ID_SCHEMA,
+    username: z.string().optional(),
+  }).optional(),
+  name: z.string(),
+})
+
+export const META_ADS_PAGE_COMMENT_SCHEMA = metaObject({
+  canComment: z.boolean().optional(),
+  canReplyPrivately: z.boolean().optional(),
+  commentCount: z.number().int().nonnegative().optional(),
+  createdTime: z.string().optional(),
+  from: metaObject({ id: z.string(), name: z.string().optional() }).optional(),
+  id: META_ADS_ID_SCHEMA,
+  likeCount: z.number().int().nonnegative().optional(),
+  message: z.string().optional(),
+  parent: metaObject({ id: z.string() }).optional(),
+})
+
+export const META_ADS_INSTAGRAM_COMMENT_SCHEMA = metaObject({
+  from: metaObject({
+    id: z.string(),
+    username: z.string().optional(),
+  }).optional(),
+  hidden: z.boolean().optional(),
+  id: META_ADS_ID_SCHEMA,
+  likeCount: z.number().int().nonnegative().optional(),
+  media: metaObject({
+    id: z.string(),
+    mediaProductType: z.string().optional(),
+  }).optional(),
+  parentId: z.string().optional(),
+  text: z.string().optional(),
+  timestamp: z.string().optional(),
+  username: z.string().optional(),
+})
+
+export const META_ADS_CREATED_OBJECT_SCHEMA = metaObject({
+  id: META_ADS_ID_SCHEMA,
+})
+
+export const META_ADS_SENT_MESSAGE_SCHEMA = metaObject({
+  messageId: META_ADS_ID_SCHEMA,
+  recipientId: z.string(),
+})
+
+export const META_ADS_CONVERSATION_SCHEMA = metaObject({
+  id: META_ADS_ID_SCHEMA,
+  updatedTime: z.string().optional(),
+})
+
+const META_ADS_MESSAGE_PARTY_SCHEMA = metaObject({
+  email: z.string().optional(),
+  id: z.string(),
+  name: z.string().optional(),
+  username: z.string().optional(),
+})
+
+export const META_ADS_CONVERSATION_MESSAGE_SCHEMA = metaObject({
+  createdTime: z.string().optional(),
+  from: META_ADS_MESSAGE_PARTY_SCHEMA.optional(),
+  id: META_ADS_ID_SCHEMA,
+  message: z.string().optional(),
+  to: metaObject({ data: META_ADS_MESSAGE_PARTY_SCHEMA.array() }).optional(),
+})

package/src/outlook/graph.ts

@@ -13,6 +13,30 @@ const GRAPH_ERROR_SCHEMA = z.looseObject({
     .optional(),
 })
 
+/** Structured error returned by a rejected Microsoft Graph request. */
+export class OutlookGraphApiError extends Error {
+  readonly retryAfter?: string
+  readonly status: number
+
+  /**
+   * Creates an error from one rejected Graph response.
+   *
+   * @param message - Diagnostic message with Graph's code and message.
+   * @param options - Rejected response details.
+   * @param options.retryAfter - Raw provider retry timing, when present.
+   * @param options.status - HTTP status.
+   */
+  constructor(
+    message: string,
+    options: { retryAfter?: string; status: number },
+  ) {
+    super(message)
+    this.name = "OutlookGraphApiError"
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
 /** Options accepted by the authenticated Outlook Graph request helper. */
 export interface OutlookGraphRequestOptions {
   /** JSON-serializable request body. */
@@ -29,8 +53,9 @@ export interface OutlookGraphRequestOptions {
  * Creates a small authenticated Microsoft Graph client for Outlook APIs.
  *
  * The raw `fetch` method is an escape hatch for provider features not yet
- * represented by a built-in action. `request` parses JSON and reports Graph
- * errors with their provider code and message.
+ * represented by a built-in action. `request` parses JSON and throws
+ * {@link OutlookGraphApiError} with Graph's code, message, status, and
+ * `Retry-After` hint.
  *
  * @param secret - Refreshed Microsoft OAuth integration secret.
  */
@@ -83,8 +108,12 @@ export function getOutlookGraphApi(secret: Record<string, unknown>) {
       const detail = [graphError?.code, graphError?.message]
         .filter(Boolean)
         .join(": ")
-      throw new Error(
+      throw new OutlookGraphApiError(
         `Microsoft Graph request failed with ${response.status} ${response.statusText}${detail ? `: ${detail}` : ""}.`,
+        {
+          retryAfter: response.headers.get("Retry-After") ?? undefined,
+          status: response.status,
+        },
       )
     }