palbase 0.8.1 → 0.9.1

package/types/internal/src/modules/analytics.d.ts

@@ -1,4 +1,221 @@
 import { type Reply, type Transport } from '../transport.js';
+/**
+ * One of the project's audiences.
+ */
+export type Audience = {
+    /**
+     * When it was last worked out.
+     */
+    computed_at?: string;
+    /**
+     * When it was made.
+     */
+    created_at: string;
+    /**
+     * What it is for.
+     */
+    description: string;
+    /**
+     * The audience.
+     */
+    id: string;
+    /**
+     * Why the last working out failed, until one succeeds.
+     */
+    last_error?: string;
+    /**
+     * How many people are in it, as of computed_at.
+     */
+    members: number;
+    /**
+     * Its name.
+     */
+    name: string;
+    rule: AudienceRule;
+    /**
+     * ready: its members are the rule's as it stands; pending: a rule made or changed is being worked out.
+     */
+    state: "ready" | "pending";
+    /**
+     * When it was last changed.
+     */
+    updated_at: string;
+};
+/**
+ * audience.entered, audience.exited: a person entered an audience, or left it.
+ */
+export type AudienceChangedEvent = {
+    /**
+     * The audience.
+     */
+    audience_id: string;
+    /**
+     * Its name when it happened.
+     */
+    audience_name: string;
+    /**
+     * The person: a user's id, or the anonymous id of an app no one signed in on.
+     */
+    person_id: string;
+    /**
+     * The user they signed in as, when they did.
+     */
+    user_id?: string;
+};
+/**
+ * One thing a person is picked by; its type says which of its fields it reads.
+ */
+export type AudienceCondition = {
+    /**
+     * event, did: how many times at least (1 unless said, 10000 at most).
+     */
+    at_least?: number;
+    /**
+     * event: true for did the event, false for did not.
+     */
+    did?: boolean;
+    /**
+     * event: the event's name (an app's own, or a platform event's type such as purchases.purchase.completed).
+     */
+    event?: string;
+    /**
+     * place: country (ISO 3166-1 alpha-2), region (a province or state, its English name) or city.
+     */
+    field?: "country" | "region" | "city";
+    /**
+     * property: the property's name.
+     */
+    key?: string;
+    /**
+     * property: eq, neq, gt, gte, lt, lte (numbers), contains (text, any case), set, not_set. place and platform: eq, neq, in. neq holds for a person the value is not known of, as not eq.
+     */
+    op?: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "set" | "not_set" | "in";
+    /**
+     * What the condition reads: event (did, or did not, an event in the last while), property (a property of the person), place (where they were last), platform (the platform their apps last sent from).
+     */
+    type: "event" | "property" | "place" | "platform";
+    /**
+     * What op compares with: a JSON scalar for a property (text compared as text, a number as a number); a string for place and platform eq and neq, a list of 1 to 50 for in. set and not_set take none.
+     */
+    value?: unknown;
+    within?: AudienceWithin;
+};
+/**
+ * An audience to make.
+ */
+export type AudienceCreate = {
+    /**
+     * What it is for.
+     */
+    description?: string;
+    /**
+     * Its name: one per project.
+     */
+    name: string;
+    rule: AudienceRule;
+};
+/**
+ * The project's audiences, by name.
+ */
+export type AudienceList = {
+    /**
+     * The audiences.
+     */
+    audiences: Audience[];
+};
+/**
+ * A person in an audience.
+ */
+export type AudienceMember = {
+    /**
+     * When they entered.
+     */
+    entered_at: string;
+    /**
+     * The installs their events came from (20 at most).
+     */
+    installations: string[];
+    /**
+     * The person: a user's id, or the anonymous id of an app no one signed in on.
+     */
+    person_id: string;
+    /**
+     * The user they signed in as, when they did.
+     */
+    user_id?: string;
+};
+/**
+ * A page of an audience's members, in the order of their id.
+ */
+export type AudienceMemberPage = {
+    /**
+     * The members.
+     */
+    members: AudienceMember[];
+    /**
+     * The next page's cursor, when there is one.
+     */
+    next_cursor?: string;
+};
+/**
+ * Who a rule would pick now.
+ */
+export type AudiencePreview = {
+    /**
+     * How many.
+     */
+    people: number;
+    /**
+     * The first twenty, by person id.
+     */
+    sample: string[];
+};
+/**
+ * A rule to try.
+ */
+export type AudiencePreviewRequest = {
+    rule: AudienceRule;
+};
+/**
+ * Who an audience is: the people every condition holds for (match all), or one at least (any).
+ */
+export type AudienceRule = {
+    /**
+     * 1 to 20.
+     */
+    conditions: AudienceCondition[];
+    /**
+     * all unless said.
+     */
+    match?: "all" | "any";
+};
+/**
+ * What to change of an audience: each field named.
+ */
+export type AudienceUpdate = {
+    /**
+     * What it is for.
+     */
+    description?: string;
+    /**
+     * Its name: one per project.
+     */
+    name?: string;
+    rule?: AudienceRule;
+};
+/**
+ * How far back an event condition looks: a year at most.
+ */
+export type AudienceWithin = {
+    /**
+     * How many units.
+     */
+    amount: number;
+    /**
+     * The unit.
+     */
+    unit: "minutes" | "hours" | "days";
+};
 export type AliasRequest = {
     /**
      * One id.
@@ -107,6 +324,67 @@ export type CaptureRequest = {
      */
     timestamp?: number;
 };
+/**
+ * Every event a project's timelines can hold: the platform modules', and those its apps and backend sent in the window.
+ */
+export type Catalog = {
+    events: CatalogEvent[];
+};
+/**
+ * An event a person's timeline can hold.
+ */
+export type CatalogEvent = {
+    /**
+     * How many the window holds (the app's).
+     */
+    count?: number;
+    /**
+     * What it is: the module's words, or the project's.
+     */
+    description?: string;
+    fields: CatalogField[];
+    /**
+     * Its first in the window (the app's).
+     */
+    first_seen?: string;
+    /**
+     * Whether the project hid it.
+     */
+    hidden: boolean;
+    /**
+     * Its newest (the app's).
+     */
+    last_seen?: string;
+    /**
+     * The module that tells it.
+     */
+    module?: string;
+    /**
+     * The event.
+     */
+    name: string;
+    /**
+     * A platform module's (module names it), or the app's: what the project's apps and backend sent.
+     */
+    source: "platform" | "app";
+};
+/**
+ * A field an event carries.
+ */
+export type CatalogField = {
+    /**
+     * What it is (a platform event's).
+     */
+    description?: string;
+    /**
+     * The field.
+     */
+    name: string;
+    /**
+     * The JSON types its values were (a platform event's: its schema's).
+     */
+    types: string[];
+};
 export type ConsoleAnswer = {
     /**
      * Records that passed.
@@ -269,6 +547,19 @@ export type EventBucket = {
      */
     users: number;
 };
+/**
+ * What the project says of one of its events.
+ */
+export type EventDefinition = {
+    /**
+     * A description its people read beside the event.
+     */
+    description: string;
+    /**
+     * Whether the catalog hides it.
+     */
+    hidden: boolean;
+};
 export type EventNames = {
     /**
      * In order.
@@ -417,6 +708,48 @@ export type PageRequest = {
      */
     url: string;
 };
+/**
+ * The people a search found, most recently seen first.
+ */
+export type PeopleFound = {
+    people: PersonFound[];
+};
+/**
+ * Properties of a person. The person is the signed-in user; with no one signed in, the app's anonymous id (distinct_id); the project's server names whom.
+ */
+export type PeopleRequest = {
+    /**
+     * Numbers added to what is set (none is 0).
+     */
+    add?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Whose properties: the anonymous id with no one signed in; the person the server means.
+     */
+    distinct_id?: string;
+    /**
+     * When the device sent it, in unix milliseconds: its clock is corrected by it.
+     */
+    sent_at?: number;
+    /**
+     * A JSON object.
+     */
+    set?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Set when not set already: where a person first came from.
+     */
+    set_once?: {
+        [key: string]: unknown;
+    };
+    /**
+     * When, in unix milliseconds; now when absent.
+     */
+    timestamp?: number;
+    unset?: string[];
+};
 export type PerfAnswer = {
     /**
      * Samples kept.
@@ -573,6 +906,78 @@ export type PerfTimeline = {
      */
     rows: PerfBucket[];
 };
+/**
+ * What is known of a person.
+ */
+export type Person = {
+    /**
+     * Its app version.
+     */
+    app_version?: string;
+    /**
+     * The city or district of their newest event that had a place (English name; DB-IP's city database), absent when none had.
+     */
+    city?: string;
+    /**
+     * Its country: ISO 3166-1 alpha-2, of their newest event that had a place.
+     */
+    country?: string;
+    /**
+     * The ids they went by: their own, and the anonymous ones identified as them.
+     */
+    distinct_ids: string[];
+    /**
+     * Their first event.
+     */
+    first_seen?: string;
+    /**
+     * The installs their events came from.
+     */
+    installations: string[];
+    /**
+     * Their newest event.
+     */
+    last_seen?: string;
+    /**
+     * Its OS version.
+     */
+    os_version?: string;
+    /**
+     * The person.
+     */
+    person_id: string;
+    /**
+     * The platform of their newest event.
+     */
+    platform?: string;
+    /**
+     * What was set of them, as it stands.
+     */
+    properties: {
+        [key: string]: unknown;
+    };
+    /**
+     * The region (a province, a state: its English name) of their newest event that had a place.
+     */
+    region?: string;
+};
+/**
+ * A person a search found.
+ */
+export type PersonFound = {
+    /**
+     * The email they were found by.
+     */
+    email?: string;
+    /**
+     * Their newest event.
+     */
+    last_seen: string;
+    /**
+     * The person: the user an anonymous id was identified as, or the id itself.
+     */
+    person_id: string;
+};
 export type RequestLine = {
     /**
      * The address it came from.
@@ -743,6 +1148,63 @@ export type Summary = {
      */
     window_seconds: number;
 };
+/**
+ * One of a person's events.
+ */
+export type TimelineEvent = {
+    /**
+     * The id it was sent under.
+     */
+    distinct_id?: string;
+    /**
+     * Its name.
+     */
+    event: string;
+    /**
+     * The event.
+     */
+    event_id: string;
+    /**
+     * The install it came from.
+     */
+    installation_id?: string;
+    /**
+     * The platform (server for the platform's).
+     */
+    platform?: string;
+    /**
+     * A JSON object.
+     */
+    properties: {
+        [key: string]: unknown;
+    };
+    /**
+     * The session.
+     */
+    session_id?: string;
+    /**
+     * Who wrote it: the app's SDK, the project's backend, or the platform (a module's event about the person).
+     */
+    source: "app" | "server" | "platform";
+    /**
+     * When (RFC 3339, milliseconds).
+     */
+    timestamp: string;
+};
+/**
+ * A page of a person's events, newest first: what their apps sent, what their backend sent, what the platform did for them.
+ */
+export type TimelinePage = {
+    events: TimelineEvent[];
+    /**
+     * The next page's cursor; absent on the last.
+     */
+    next_cursor?: string;
+    /**
+     * The person the id asked for is: an anonymous id identified as a user is that user.
+     */
+    person_id: string;
+};
 export type Trace = {
     /**
      * Whose.
@@ -973,8 +1435,94 @@ export type TraceTimeline = {
      */
     rows: TraceHour[];
 };
+/** The events this module sends the project's webhooks (x-palbase-events), by type: each one's payload, the event's data. */
+export interface Events {
+    /**
+     * audience.entered: a person came to be in an audience — what they did, or what was set of them, made its rule pick them.
+     */
+    "audience.entered": AudienceChangedEvent;
+    /**
+     * audience.exited: a person left an audience — its rule no longer picks them (a window passed, a property changed).
+     */
+    "audience.exited": AudienceChangedEvent;
+}
 /** Palbase Analytics */
 export declare function client(t: Transport): {
+    /**
+     * List audiences
+     *
+     * The project's audiences, by name: each one's rule, how many people are in it, and whether its members are the rule's as it stands (ready) or a rule made or changed is still being worked out (pending).
+     */
+    listAudiences(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, AudienceList>>;
+    /**
+     * Create an audience
+     *
+     * Makes an audience: the people its rule picks among those behind the project's events. Its members are worked out at once, then every minute; its first members are not told they entered (the rule came to them), everyone who enters or leaves from then on is (audience.entered, audience.exited). A project keeps 100 audiences at most.
+     */
+    createAudience(input: {
+        body: AudienceCreate; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, Audience>>;
+    /**
+     * Preview an audience's rule
+     *
+     * Who a rule would pick now — how many, and the first twenty — without keeping it.
+     */
+    previewAudience(input: {
+        body: AudiencePreviewRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, AudiencePreview>>;
+    /**
+     * Get an audience
+     *
+     * One audience.
+     */
+    getAudience(input: {
+        path: {
+            id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Audience>>;
+    /**
+     * Delete an audience
+     *
+     * Deletes an audience and its members; no one is told they left.
+     */
+    deleteAudience(input: {
+        path: {
+            id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * Change an audience
+     *
+     * Changes what the request names. A changed rule is worked out anew and, like a new one, without telling anyone who it picks at once.
+     */
+    updateAudience(input: {
+        path: {
+            id: string;
+        };
+        body: AudienceUpdate; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Audience>>;
+    /**
+     * List an audience's members
+     *
+     * A page of the audience's members as of its latest working out, in the order of their id: each one's person id, the user they signed in as when they did, and the installs their events came from.
+     */
+    listAudienceMembers(input: {
+        path: {
+            id: string;
+        };
+        query?: {
+            limit?: number; /** Where the page starts: a next_cursor this API gave. */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, AudienceMemberPage>>;
     /**
      * Join two ids
      *
@@ -1012,7 +1560,7 @@ export declare function client(t: Transport): {
      */
     getEventBreakdown(input: {
         query: {
-            window_seconds?: number; /** What to split by: platform, app_version, os_version, country, event (the event's name), or property:<key> — a key of the events' properties (letters, digits and _ . $ -, 64 at most). */
+            window_seconds?: number; /** What to split by: platform, app_version, os_version, country, region (a province, a state: its English name), city, event (the event's name), or property:<key> — a key of the events' properties (letters, digits and _ . $ -, 64 at most). */
             by: string; /** Only this event (every event unless said). */
             event?: string; /** Values per page (10 unless said). */
             limit?: number; /** The next_cursor of the page before: reads the page after it. */
@@ -1410,5 +1958,74 @@ export declare function client(t: Transport): {
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, TraceTimeline>>;
+    /**
+     * Find people
+     *
+     * Finds people by an id they went by — a user's, an anonymous one, an install's — or by their email ($email, email), most recently seen first.
+     */
+    searchPeople(input: {
+        query: {
+            query: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, PeopleFound>>;
+    /**
+     * Set a person's properties
+     *
+     * Sets properties of a person: the signed-in user, with no one signed in the app's anonymous id, or — the project's server — whom it names. set replaces, set_once sets what is not set (where they first came from), unset removes, add adds a number. The anonymous id's properties are the user's once it is identified as them.
+     */
+    setPersonProperties(input: {
+        body: PeopleRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<202, undefined>>;
+    /**
+     * Get a person
+     *
+     * What is known of a person: the ids they went by (an anonymous id identified as a user is that user), the installs their events came from, their properties as they stand, when they were first and last seen, and the context of their newest event.
+     */
+    getPerson(input: {
+        path: {
+            person_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Person>>;
+    /**
+     * List a person's events
+     *
+     * A page of a person's events, newest first: every event under an id they went by — what their apps sent, what their backend sent, and what the platform's modules did for them (a purchase, a push that reached their phone, a consent changed) — and the platform's events about an install of theirs no one was signed in on.
+     */
+    listPersonEvents(input: {
+        path: {
+            person_id: string;
+        };
+        query?: {
+            limit?: number; /** The next_cursor of the page before: reads the page after it. */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, TimelinePage>>;
+    /**
+     * Get the event catalog
+     *
+     * Every event a project's timelines can hold, with the fields each carries: the platform modules' (their contracts'), and those the project's apps and backend sent in the window (30 days unless said), with how many and the JSON types their properties were — and what the project said of each.
+     */
+    getEventCatalog(input?: {
+        query?: {
+            window_seconds?: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Catalog>>;
+    /**
+     * Describe an event
+     *
+     * Says what an event is, and whether the catalog hides it.
+     */
+    defineEvent(input: {
+        path: {
+            name: string;
+        };
+        body: EventDefinition; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, EventDefinition>>;
 };
 export type Client = ReturnType<typeof client>;