@iann29/rastro 0.9.0 → 0.10.1

package/dist/component/metaSync.d.ts

@@ -0,0 +1,186 @@
+import type { Doc } from "./_generated/dataModel.js";
+import { type MutationCtx } from "./_generated/server.js";
+export declare const SYNC_INTERVAL_MS: number;
+/** `nextSyncAt` of an account the chain must not take: its token failed. */
+export declare const PAUSED_AT: number;
+/** A link to one connection at most; the chain pauses and resumes them all. */
+export declare const MAX_LINKS_PER_CONNECTION = 500;
+/** Above this share of any Meta rate limit, the next sync waits longer. */
+export declare const USAGE_BACKOFF_PCT = 75;
+/** The account-local calendar date of an instant, `YYYY-MM-DD`. */
+export declare function localDate(timestamp: number, timeZone: string): string;
+export declare function dateDayStart(date: string): number;
+export type SyncRange = {
+    since: string;
+    until: string;
+};
+export type SyncPlan = {
+    kind: "backfill";
+    range: SyncRange;
+    /** The date the next block starts from, or null when this is the last. */
+    nextFrom: string | null;
+    fullCatalog: boolean;
+} | {
+    kind: "live";
+    range: SyncRange;
+    fullCatalog: boolean;
+    daily: boolean;
+    weekly: boolean;
+};
+/** What one run of an account reads from Meta, by its state and the time. */
+export declare function planSync(account: Pick<Doc<"siteAdAccounts">, "timezone" | "lastSyncAt" | "lastDailyResyncAt" | "lastFullResyncAt" | "backfillFrom">, now: number): SyncPlan;
+/** The wait after `failures` failed runs in a row: 15 min doubling to 6 h. */
+export declare function retryDelay(failures: number): number;
+/**
+ * Makes sure the chain runs by `at`: starts it, or pulls a later run earlier.
+ * Called by every write that gives the chain work.
+ */
+export declare function kickSyncLoop(ctx: MutationCtx, at: number): Promise<void>;
+/** One link of the chain: hands the due accounts to fresh runs, moves on. */
+export declare const loop: import("convex/server").RegisteredMutation<"internal", {}, Promise<null>>;
+export declare const loadJob: import("convex/server").RegisteredQuery<"internal", {
+    runId: string;
+    siteAdAccountId: import("convex/values").GenericId<"siteAdAccounts">;
+}, Promise<{
+    siteId: import("convex/values").GenericId<"sites">;
+    adAccountId: string;
+    timezone: string;
+    lastSyncAt: number | undefined;
+    lastDailyResyncAt: number | undefined;
+    lastFullResyncAt: number | undefined;
+    backfillFrom: string | undefined;
+    connectionActive: boolean;
+    tokenCipher: string;
+    tokenIv: string;
+} | null>>;
+/**
+ * Upserts one chunk of spend rows, stamping them with the run's start, and
+ * keeps the site-day aggregate in step. `stop` when the run lost the link.
+ */
+export declare const saveSpend: import("convex/server").RegisteredMutation<"internal", {
+    rows: {
+        adId: string;
+        clicks: number;
+        conversations: number;
+        dayStart: number;
+        impressions: number;
+        spendCents: number;
+    }[];
+    runId: string;
+    siteAdAccountId: import("convex/values").GenericId<"siteAdAccounts">;
+    syncedAt: number;
+}, Promise<{
+    stop: boolean;
+}>>;
+/**
+ * After a complete range is saved, drops the account's rows in it that the
+ * run did not touch: Meta leaves out an ad-day with nothing, so a day
+ * corrected to zero disappears from its answer. Pages until done.
+ */
+export declare const dropStaleSpend: import("convex/server").RegisteredMutation<"internal", {
+    cursor: string | null;
+    firstDay: number;
+    lastDay: number;
+    runId: string;
+    siteAdAccountId: import("convex/values").GenericId<"siteAdAccounts">;
+    syncedAt: number;
+}, Promise<{
+    stop: boolean;
+    done: boolean;
+    cursor: null;
+} | {
+    stop: boolean;
+    done: boolean;
+    cursor: string;
+}>>;
+/**
+ * Names, status and creative for the account's ads. A missing field keeps the
+ * stored value. Returns the ads that have a thumbnail at Meta but none in
+ * storage yet; `stop` when the run lost the link.
+ */
+export declare const upsertCatalog: import("convex/server").RegisteredMutation<"internal", {
+    ads: {
+        adId: string;
+        adName?: string | undefined;
+        adStatus?: string | undefined;
+        adsetId?: string | undefined;
+        adsetName?: string | undefined;
+        campaignId?: string | undefined;
+        campaignName?: string | undefined;
+        creativeType?: "carousel" | "image" | "other" | "video" | undefined;
+        hasThumbnail?: boolean | undefined;
+    }[];
+    runId: string;
+    siteAdAccountId: import("convex/values").GenericId<"siteAdAccounts">;
+}, Promise<{
+    stop: boolean;
+    needThumbnail: string[];
+}>>;
+export declare const setThumbnail: import("convex/server").RegisteredMutation<"internal", {
+    adId: string;
+    siteId: import("convex/values").GenericId<"sites">;
+    storageId: import("convex/values").GenericId<"_storage">;
+}, Promise<null>>;
+/**
+ * Ads that brought the site leads lately but have no name yet, to ask the
+ * account for. An ad the catalog already files under another account is not
+ * this account's to name.
+ */
+export declare const missingAdNames: import("convex/server").RegisteredQuery<"internal", {
+    adAccountId: string;
+    since: number;
+    siteId: import("convex/values").GenericId<"sites">;
+}, Promise<string[]>>;
+/** Records how a run ended and when the account syncs next. */
+export declare const finishSync: import("convex/server").RegisteredMutation<"internal", {
+    adAccountId: string;
+    outcome: {
+        kind: "ok";
+        plan: {
+            kind: "backfill";
+            nextFrom: string | null;
+        } | {
+            daily: boolean;
+            kind: "live";
+            weekly: boolean;
+        };
+        regainMs: number | null;
+        truncated: boolean;
+        usagePct: number;
+    } | {
+        kind: "key" | "other" | "permission" | "throttled" | "token";
+        message: string;
+        regainMs: number | null;
+    };
+    runId: string;
+    siteAdAccountId: import("convex/values").GenericId<"siteAdAccounts">;
+    siteId: import("convex/values").GenericId<"sites">;
+    startedAt: number;
+    tokenIv: string;
+}, Promise<null>>;
+/** Reads one account from Meta and writes what it found, as run `runId`. */
+export declare const syncAccount: import("convex/server").RegisteredAction<"internal", {
+    runId: string;
+    siteAdAccountId: import("convex/values").GenericId<"siteAdAccounts">;
+}, Promise<null>>;
+/**
+ * Deletes a site's spend from one ad account after it is unlinked, a batch
+ * per run, then its site-day aggregate. Stops if the account is linked to the
+ * site again meanwhile (its backfill rewrites the rows).
+ */
+export declare const purgeSpend: import("convex/server").RegisteredMutation<"internal", {
+    adAccountId: string;
+    cursor: string | null;
+    siteId: import("convex/values").GenericId<"sites">;
+}, Promise<null>>;
+/**
+ * How far the first backfill has read, from the cursor the chain keeps:
+ * whole 30-day blocks done of the 90 days' total. Null once the account has
+ * synced (a later gap fill runs under `live`). Reads no clock: the range is
+ * counted from the account-local date it was linked on.
+ */
+export declare function backfillProgress(link: Pick<Doc<"siteAdAccounts">, "lastSyncAt" | "backfillFrom" | "createdAt" | "timezone">): {
+    done: number;
+    total: number;
+} | null;
+//# sourceMappingURL=metaSync.d.ts.map

package/dist/component/metaSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaSync.d.ts","sourceRoot":"","sources":["../../src/component/metaSync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAM,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,wBAAwB,CAAC;AA+BhC,eAAO,MAAM,gBAAgB,QAAc,CAAC;AAC5C,4EAA4E;AAC5E,eAAO,MAAM,SAAS,QAA0B,CAAC;AACjD,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAO5C,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAuBpC,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD;AAOD,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,QAAQ,GAChB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;CACtB,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEN,6EAA6E;AAC7E,wBAAgB,QAAQ,CACtB,OAAO,EAAE,IAAI,CACX,GAAG,CAAC,gBAAgB,CAAC,EACnB,UAAU,GACV,YAAY,GACZ,mBAAmB,GACnB,kBAAkB,GAClB,cAAc,CACjB,EACD,GAAG,EAAE,MAAM,GACV,QAAQ,CA0CV;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAKD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,iBAsB9D;AAED,6EAA6E;AAC7E,eAAO,MAAM,IAAI,2EAyDf,CAAC;AAmBH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;UAsClB,CAAC;AAuDH;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;GAqDpB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;GA0CzB,CAAC;AAsBH;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;GA2CxB,CAAC;AAEH,eAAO,MAAM,YAAY;;;;iBA2BvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;qBAkCzB,CAAC;AAmCH,+DAA+D;AAC/D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;iBAsHrB,CAAC;AA2HH,4EAA4E;AAC5E,eAAO,MAAM,WAAW;;;iBA+LtB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;iBA0CrB,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,CACR,GAAG,CAAC,gBAAgB,CAAC,EACrB,YAAY,GAAG,cAAc,GAAG,WAAW,GAAG,UAAU,CACzD,GACA;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAgBxC"}