1
import { z } from "../../framework";
2

3
import { FailedAPIOperationSchema } from "../common";
4
import { ProjectIdSchema } from "../projects/common";
5

6
import {
7
  DayStatementIdSchema,
8
  InvoiceIdSchema,
9
  MonthStatementIdSchema,
10
  PurchaseIdSchema,
11
} from "./common";
12

13
const PurchaseServiceSchema = z
14
  .string()
15
  .describe("The service being charged for, e.g., `openai-gpt-4`, etc.");
16

17
// OpenAPI spec
18
//
19
export const GetPurchasesInputSchema = z
20
  .object({
21
    limit: z
22
      .number()
23
      .default(100)
24
      .describe("Upper bound on the number of purchases to return.")
25
      .nullish(),
26
    offset: z
27
      .number()
28
      .describe("Number of purchases by which to offset results.")
29
      .nullish(),
30
    service: PurchaseServiceSchema.nullish(),
31
    compute_server_id: z
32
      .number()
33
      .describe(
34
        "Only get purchases involving this compute server.  The id must be the *global* compute server id, not the one local to this project.   NOTE: This gets purchases for whoever is the *owner* of the compute server, which might not be the user requesting the purchases.",
35
      )
36
      .nullish(),
37
    project_id: ProjectIdSchema.describe(
38
      "Only get purchases involving this project made by the client making this request.  This does not get purchases by other collaborators in this project.",
39
    ).nullish(),
40
    group: z
41
      .boolean()
42
      .describe(
43
        `If \`true\`, results are groups by service and project id, and then decreasingly
44
         ordered by cost. Otherwise, results are ordered by time, with the newest
45
         purchases returned first.`,
46
      )
47
      .nullish(),
48
    cutoff: z
49
      .union([z.string(), z.number()])
50
      .describe(
51
        `When provided, only purchases which occur _after_ the timestamp specified in this
52
         field will be returned.`,
53
      )
54
      .nullish(),
55
    thisMonth: z
56
      .boolean()
57
      .describe(
58
        "If `true`, only purchases since the most recent closing date will be returned.",
59
      )
60
      .nullish(),
61
    day_statement_id: DayStatementIdSchema.describe(
62
      "Daily statement id of the statement that includes this purchase",
63
    ).nullish(),
64
    month_statement_id: MonthStatementIdSchema.describe(
65
      "Monthly statement id of the statement that includes this purchase",
66
    ).nullish(),
67
    no_statement: z
68
      .boolean()
69
      .describe(
70
        `If \`true\`, only purchases which are
71
         _not_ associated with a monthly or daily statement are returned.`,
72
      )
73
      .nullish(),
74
  })
75
  .describe("Gets user purchases.");
76

77
export const GetPurchasesOutputSchema = z.union([
78
  FailedAPIOperationSchema,
79
  z
80
    .object({
81
      balance: z
82
        .number()
83
        .describe(
84
          `The account balance after this purchase was made.  For in progress PAYG purchases, e.g., compute servers, this can be complicated -- it's the balance when the purchases table was requested, incorporating the contribution of this purchase so far.`,
85
        ),
86
      purchases: z.array(
87
        z.object({
88
          id: PurchaseIdSchema,
89
          time: z.string().describe("Time at which this purchase was logged."),
90
          cost: z.number().describe(
91
            `The cost in US dollars. Not set if the purchase isn't finished, e.g., when
92
         upgrading a project this is only set when project stops or purchase is finalized.
93
         This takes precedence over the \`cost_per_hour\` times the length of the period
94
         when active.`,
95
          ),
96
          period_start: z.string().describe(
97
            `When the purchase starts being active (e.g., a 1 week license starts and ends on
98
         specific days; for metered purchases it is when the purchased started charging) `,
99
          ),
100
          period_end: z.string().describe(
101
            `When the purchase stops being active. For metered purchases, it's when the
102
         purchase finished being charged, in which case the cost field should be equal to
103
         the length of the period times the \`cost_per_hour\`.`,
104
          ),
105
          cost_per_hour: z.number().describe(
106
            `The cost in US dollars per hour. This is used to compute the cost so far for
107
         metered purchases when the cost field isn't set yet. The cost so far is the
108
         number of hours since \`period_start\` times the \`cost_per_hour\`. The
109
         description field may also contain redundant cost per hour information, but this
110
         \`cost_per_hour\` field is the definitive source of truth. Once the \`cost\`
111
         field is set, this \`cost_per_hour\` is just useful for display purposes.`,
112
          ),
113
          cost_so_far: z.number().describe(
114
            `The cost so far in US dollars for a metered purchase that accumulates. This is
115
         used, e.g., for data transfer charges.`,
116
          ),
117
          service: PurchaseServiceSchema,
118
          description: z.map(z.string(), z.any()).describe(
119
            `An object that provides additional details about what was purchased and can have
120
         an arbitrary format. This is mainly used to provide extra insight when rendering
121
         this purchase for users, and its content should not be relied on for queries.`,
122
          ),
123
          invoice_id: InvoiceIdSchema.nullable().describe(
124
            `The id of the Stripe invoice that was sent that included this item. May be
125
           null. **Legacy Behavior:** if paid via a payment intent, this will be the id of
126
           a payment intent instead, and it will start with \`pi_\`.`,
127
          ),
128
          project_id: ProjectIdSchema.nullable().describe(
129
            `The id of the project where this purchase happened. Not all purchases
130
         necessarily involve a project, and so this field may be null.`,
131
          ),
132
          pending: z
133
            .boolean()
134
            .nullable()
135
            .describe(
136
              `If \`true\`, then this transaction is considered pending, which means that
137
            for a few days it doesn't count against the user's quotas for the purposes of
138
            deciding whether or not a purchase is allowed. This is needed so we can charge
139
            a user for their subscriptions, then collect the money from them, without all
140
            of the running pay-as-you-go project upgrades suddenly breaking (etc.).`,
141
            ),
142
          note: z
143
            .string()
144
            .nullable()
145
            .describe(
146
              `Non-private notes about this purchase. The user has read-only access to this
147
           field.`,
148
            ),
149
        }),
150
      ),
151
    })
152
    .describe(
153
      `An array of purchases filtered and/or grouped according to the provided request
154
       body.`,
155
    ),
156
]);
157

158
export type GetPurchasesInput = z.infer<typeof GetPurchasesInputSchema>;
159
export type GetPurchasesOutput = z.infer<typeof GetPurchasesOutputSchema>;
160

161