Tinybird Analytics Engine | blade47/dub Wiki | doc0

Public

Tinybird Analytics Engine | blade47/dub Wiki | doc0

Endpoint / Pipe Variable	Target Source / Pipe	Configuration / Schema Constraints	Source File
`recordClickZod`	`dub_click_events`	`wait: true`, uses `recordClickZodSchema` (with default fallback strings/numbers for geographic, device, and request properties)	apps/web/lib/tinybird/record-click-zod.ts:39-43
`recordWebhookEvent`	`dub_webhook_events`	Omits `timestamp` from `webhookEventSchemaTB`	apps/web/lib/tinybird/record-webhook-event.ts:4-7
`recordPostbackEvent`	`dub_postback_events`	Omits `timestamp` from `postbackEventInputSchemaTB`	apps/web/lib/postback/record-postback-event.ts:4-7
`pipe` (`getCustomerEventsTB`)	`v2_customer_events`	Parameters and data typed via `z.any()` placeholders	apps/web/lib/tinybird/get-customer-events-tb.ts:4-8

export const getCustomerEventsTB = async ({
  customerId,
  linkIds,
  limit,
}: {
  customerId: string;
  linkIds?: string[];
  limit?: number;
}) => {
  return await pipe({
    customerId,
    ...(linkIds ? { linkIds } : {}),
    ...(limit ? { limit } : {}),
  });
};

Field Name	Type / Zod Definition	Default Value	Source File
`timestamp`	`z.string()`	`""`	apps/web/lib/tinybird/record-click-zod.ts:5
`identity_hash`	`z.string()`	`""`	apps/web/lib/tinybird/record-click-zod.ts:6
`click_id`	`z.string()`	`""`	apps/web/lib/tinybird/record-click-zod.ts:7
`workspace_id`	`z.string()`	`""`	apps/web/lib/tinybird/record-click-zod.ts:8
`link_id`	`z.string()`	`""`	apps/web/lib/tinybird/record-click-zod.ts:9
`domain`	`z.string()`	`""`	apps/web/lib/tinybird/record-click-zod.ts:10
`key`	`z.string()`	`""`	apps/web/lib/tinybird/record-click-zod.ts:11
`country`	`z.string()`	`"Unknown"`	apps/web/lib/tinybird/record-click-zod.ts:15
`device`	`z.string()`	`"Desktop"`	apps/web/lib/tinybird/record-click-zod.ts:21
`browser`	`z.string()`	`"Unknown"`	apps/web/lib/tinybird/record-click-zod.ts:24
`os`	`z.string()`	`"Unknown"`	apps/web/lib/tinybird/record-click-zod.ts:28
`bot`	`z.number()`	`0`	apps/web/lib/tinybird/record-click-zod.ts:32
`qr`	`z.number()`	`0`	apps/web/lib/tinybird/record-click-zod.ts:33
`referer`	`z.string()`	`"(direct)"`	apps/web/lib/tinybird/record-click-zod.ts:34
`trigger`	`z.string()`	`"link"`	apps/web/lib/tinybird/record-click-zod.ts:36

Endpoint Function	Datasource	Event Schema Source	Sources
`recordLead`	`dub_lead_events`	`leadEventSchemaTB`	apps/web/lib/tinybird/record-lead.ts:5-8
`recordLeadWithTimestamp`	`dub_lead_events`	`leadEventSchemaTB.extend({ timestamp: z.string() })`	apps/web/lib/tinybird/record-lead.ts:10-15
`recordSale`	`dub_sale_events`	`saleEventSchemaTB`	apps/web/lib/tinybird/record-sale.ts:5-8
`recordSaleWithTimestamp`	`dub_sale_events`	`saleEventSchemaTB.extend({ timestamp: z.string() })`	apps/web/lib/tinybird/record-sale.ts:10-15

export const POST = withPublishableKey(
  async ({ req, workspace }) => {
    const body = await parseRequestBody(req);
 
    const allowRequest = verifyAnalyticsAllowedHostnames({
      allowedHostnames: (workspace?.allowedHostnames ?? []) as string[],
      req,
    });
 
    if (!allowRequest) {
      throw new DubApiError({
        code: "forbidden",
        message: `Request origin '${getHostnameFromRequest(req)}' is not included in the allowed hostnames for this workspace.`,
      });
    }
 
    const parsed = trackLeadRequestSchema.parse(body);
    const response = await trackLead({ ...parsed, workspace });
    return NextResponse.json(response, { headers: COMMON_CORS_HEADERS });
  },
  {
    requiredPlan: ["business", "advanced", "enterprise"],
  },
);

Schema Name	Target Source / Datasource	Key Validation Rules
`trackLeadRequestSchema`	API Request Payload	`clickId` (string, trim), `eventName` (1-255 chars), `customerExternalId` (1-100 chars), `mode` (`async`, `wait`, `deferred`)
`leadEventSchemaTB`	Tinybird Ingestion (`dub_leads`)	Omits `timestamp` (generated by Tinybird), extends `clickEventSchemaTB` with `event_id`, `event_name`, `customer_id`, `metadata`
`dubLinksMetadataSchema`	Tinybird Ingestion (`dub_links_metadata`)	Transforms `created_at` date to SQL string format, maps `deleted` boolean to integer (`1`/`0`), sets defaults for nullable IDs

const transformLinkTB = (link: ExpandedLink) => {
  const key = decodeKeyIfCaseSensitive({
    domain: link.domain,
    key: link.key,
  });
 
  return {
    link_id: link.id,
    domain: link.domain,
    key,
    url: link.url,
    tag_ids: link.tags?.map(({ tag }) => tag.id) ?? [],
    folder_id: link.folderId ?? "",
    tenant_id: link.tenantId ?? "",
    program_id: link.programId ?? "",
    partner_id: link.partnerId ?? "",
    partner_group_id: link.programEnrollment?.groupId ?? "",
    partner_tag_ids:
      link.programEnrollment?.programPartnerTags?.map(
        ({ partnerTagId }) => partnerTagId,
      ) ?? [],
    workspace_id: link.projectId,
    created_at: link.createdAt,
  };
};

Webhook Event	Segment Event Name	User ID Source	Properties Included
`link.clicked`	`Link Clicked`	`click.id` (anonymousId)	`click`, `link`
`lead.created`	`capitalize(eventName)`	`customer.externalId`	`click`, `link`, `customer`
`sale.created`	`capitalize(eventName)`	`customer.externalId`	`click`, `link`, `customer`, `sale`, `revenue`, `currency`
`partner.enrolled`	`Partner Enrolled`	`partner.id`	`partner`, `links`

export const getLeadEvent = async ({
  customerId,
  eventName,
}: {
  customerId: string;
  eventName?: string | null;
}) => {
  try {
    const cachedLeadEvent = await redis.get<LeadEventTB>(
      `leadCache:${customerId}${eventName ? `:${eventName.toLowerCase().replaceAll(" ", "-")}` : ""}`,
    );
 
    if (cachedLeadEvent) {
      return cachedLeadEvent;
    }
  } catch (_e) {}
 
  try {
    const { data } = await getLeadEventTB({ customerId, eventName });
    return data[0];
  } catch (error) {
    console.error(
      `[getLeadEvent] Error getting lead event for customerId: ${customerId}${eventName ? ` and eventName: ${eventName}` : ""}`,
      error,
    );
    return null;
  }
};

Pipe Function	Target Pipe / Datasource	Parameter Validation Schema	Purpose
`getAnalytics` (MySQL shortcut)	`Link` (MySQL table via PlanetScale)	N/A	Fast retrieval of all-time counts when `interval === "all"`, no custom dates/filters are set
`tb.buildPipe` (`getAnalytics`)	`v4_count`, `v4_timeseries`, `v4_group_by_link_metadata`, `v4_group_by`	`analyticsFilterTB`	Timeseries and dimensional grouping metrics (clicks, leads, sales, sale amount)
`tb.buildPipe` (`getEvents`)	`v4_events`	`eventsFilterTB`	Paginated raw event logs for clicks, leads, and sales with metadata parsing
`getLeadEvents`	`get_lead_events`	`z.object({ customerIds: z.string().array() })`	Batch retrieval of lead events for a list of customer identifiers
`getLeadEventTB`	`get_lead_event`	`z.object({ customerId: z.string(), eventName: z.string().nullish() })`	Single lead event lookup filtered by customer ID and optional event name

Maintenance Script	Target Datasources	Deletion / Update Mechanism	Purpose
`delete-lead-event.ts`	`dub_lead_events`, `dub_lead_events_mv`	POST `delete_condition=customer_id = '...'`	Purge specific customer lead events across base and materialized views
`update-lead-event.ts`	`dub_lead_events`, `dub_lead_events_mv`	Fetch via `internal_get_lead_events` pipe $\rightarrow$ record via `recordLeadWithTimestamp` $\rightarrow$ delete old `link_id`	Migrate customer lead association from an old link to a new link
`update-sale-event.ts`	`dub_sale_events`, `dub_sale_events_mv`	Fetch via `internal_get_sale_events` pipe $\rightarrow$ record via `recordSaleWithTimestamp` $\rightarrow$ delete old `link_id`	Migrate customer sale records to a corrected partner link
`update-sale-events.ts` (Beehiiv)	`dub_sale_events`, `dub_sale_events_mv`	Fetch via `internal_get_events` pipe $\rightarrow$ record via `recordSaleWithTimestamp` $\rightarrow$ delete by `link_id` and customer ID	Batch update Beehiiv customer sale event link attributions