@signsealer/sdk 1.30.0 → 1.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -263,6 +263,72 @@ export interface Settings {
263
263
  default_language: string;
264
264
  };
265
265
  }
266
+ /** 1.32.0 (00807): a payment a managed business is asked for by its partner, on the partner's own Stripe account. */
267
+ export interface PartnerCharge {
268
+ id: string;
269
+ /** `invoice`, a month in arrears; `topup`, credit bought; `reload`, its automatic reload. */
270
+ kind: "invoice" | "topup" | "reload";
271
+ /** YYYY-MM, for an invoice. */
272
+ month: string | null;
273
+ cents: number;
274
+ currency: "usd";
275
+ status: "pending" | "open" | "paid" | "failed" | "void" | "uncollectible" | "unmade";
276
+ created_at: string;
277
+ paid_at: string | null;
278
+ refunded_cents: number;
279
+ /** Stripe's own pages: to pay it or see it, and its PDF. */
280
+ hosted_url: string | null;
281
+ pdf_url: string | null;
282
+ lines: Array<{
283
+ description: string;
284
+ cents: number;
285
+ item?: string;
286
+ quantity?: number;
287
+ }>;
288
+ }
289
+ /**
290
+ * 1.32.0 (00807): what a managed business pays its partner, in the partner's
291
+ * name and prices (`GET /v1/billing`). Read with `partner.business(id)`.
292
+ */
293
+ export interface BusinessBilling {
294
+ partner: string;
295
+ mode: "none" | "invoice" | "prepaid";
296
+ /** The partner's Stripe account is connected and takes payments. */
297
+ ready: boolean;
298
+ currency: "usd";
299
+ plan: {
300
+ name: string;
301
+ monthly_cents: number | null;
302
+ yearly_cents: number | null;
303
+ interval: "monthly" | "yearly" | null;
304
+ };
305
+ prices: Record<string, number>;
306
+ /** Its prepaid credit with the partner; below zero is what it owes. */
307
+ balance_cents: number;
308
+ gift_left_cents: number;
309
+ month: {
310
+ month: string;
311
+ cents: number;
312
+ gift_used_cents: number;
313
+ to_bill_cents: number;
314
+ items: Array<{
315
+ item: string;
316
+ draws: number;
317
+ cents: number;
318
+ }>;
319
+ };
320
+ card: {
321
+ brand: string | null;
322
+ last4: string;
323
+ } | null;
324
+ reload: {
325
+ enabled: boolean;
326
+ below_cents: number | null;
327
+ amount_cents: number | null;
328
+ };
329
+ unpaid: boolean;
330
+ charges: PartnerCharge[];
331
+ }
266
332
  /** What `updateSettings` changes: only what is named; null clears it (00792). */
267
333
  export interface SettingsChanges {
268
334
  brand_name?: string | null;
@@ -1256,7 +1322,7 @@ export interface ClientOptions {
1256
1322
  userAgent?: string;
1257
1323
  }
1258
1324
  /** This package's version, as `package.json` has it; `tests/sdk.ts` holds the two together. */
1259
- export declare const SDK_VERSION = "1.30.0";
1325
+ export declare const SDK_VERSION = "1.32.0";
1260
1326
  /** What a client built with a secret key in a web page throws (1.26.0). */
1261
1327
  export declare const KEY_IN_PAGE_MESSAGE: string;
1262
1328
  export declare class SignSealer {
@@ -1304,6 +1370,26 @@ export declare class SignSealer {
1304
1370
  applyForTextingNumber(application: TextingNumberApplication): Promise<TextingNumberState>;
1305
1371
  /** The business's own texting number, its application's steps, and the carriers' wording (00792). */
1306
1372
  textingNumber(): Promise<TextingNumberState>;
1373
+ /**
1374
+ * 1.32.0 (00807): what a managed business pays you, its partner, on your
1375
+ * own Stripe account: its plan, how it pays, its credit or this month so
1376
+ * far, its card, its invoices and receipts. With `partner.business(id)`.
1377
+ */
1378
+ billing(): Promise<BusinessBilling>;
1379
+ /**
1380
+ * 1.32.0 (00807): a managed business's automatic reload, off. Turning it on
1381
+ * is taken only from an embedded Billing screen session with the `admin`
1382
+ * role that you minted (`embedSession`), with the sentence agreed to there;
1383
+ * it proves an admin session you issued, not who the person is. From your
1384
+ * key it is refused with 403. A
1385
+ * PATCH of the same values, so a retry sets the same thing again.
1386
+ */
1387
+ setBillingReload(reload: {
1388
+ enabled: boolean;
1389
+ below_cents?: number;
1390
+ amount_cents?: number;
1391
+ consent?: string;
1392
+ }): Promise<BusinessBilling>;
1307
1393
  /** Prove the key works, and say whose account it is. */
1308
1394
  account(): Promise<Account>;
1309
1395
  /** Every version of every template, newest first; `code` narrows it to one template's versions. No text: `template(id)` has that. */
@@ -2953,10 +3039,56 @@ export interface PartnerPriceList {
2953
3039
  id_check?: number;
2954
3040
  markup_bp?: number;
2955
3041
  }
2956
- /** 00759: your price list, and what each unit is. */
3042
+ /**
3043
+ * 00806: what we charge you for one item today: your own price where your
3044
+ * agreement with us sets one (`deal`, from `from` to `until`, the last day it
3045
+ * applies), our public price where it does not. In cents; a metered public
3046
+ * price may be a fraction of one, and null is an item not sold yet.
3047
+ */
3048
+ export interface PartnerChargedItem {
3049
+ item: string;
3050
+ label: string;
3051
+ /** Our public price for one, for a business starting today. */
3052
+ public_cents: number | null;
3053
+ /** The lowest and highest across the versions of our prices your businesses are on (a business keeps its version until its renewal after notice). */
3054
+ public_low: number | null;
3055
+ public_high: number | null;
3056
+ /** What we charge you for one, for a business starting today. */
3057
+ cents: number | null;
3058
+ cents_low: number | null;
3059
+ cents_high: number | null;
3060
+ deal: boolean;
3061
+ from: string | null;
3062
+ until: string | null;
3063
+ }
3064
+ /** 00806: a day ahead when what we charge you for an item changes, and to what. */
3065
+ export interface PartnerScheduledPrice {
3066
+ item: string;
3067
+ label: string;
3068
+ /** The first day (UTC) of the new price. */
3069
+ from: string;
3070
+ cents: number | null;
3071
+ public_cents: number | null;
3072
+ deal: boolean;
3073
+ /** A rise: where the email telling it stands. It comes in 30 full days after that email is sent, and not before `from`. */
3074
+ notice?: {
3075
+ state: "waiting" | "sent" | "in_force" | "undelivered";
3076
+ sent_at: string | null;
3077
+ in_force_from: string | null;
3078
+ } | null;
3079
+ }
3080
+ /** 00806: what we charge you, today and next. A price that goes up is told to your owner thirty days before (`notice_days`). */
3081
+ export interface PartnerCharged {
3082
+ as_of: string;
3083
+ notice_days: number;
3084
+ items: PartnerChargedItem[];
3085
+ scheduled: PartnerScheduledPrice[];
3086
+ }
3087
+ /** 00759: your price list, and what each unit is; 00806: and what we charge you. */
2957
3088
  export interface PartnerPrices {
2958
3089
  prices: PartnerPriceList;
2959
3090
  units: Record<string, string>;
3091
+ charged: PartnerCharged;
2960
3092
  }
2961
3093
  /** 00760: one of your webhook endpoints, copied onto every business you made (of its mode). */
2962
3094
  export interface PartnerWebhook {
@@ -2996,6 +3128,91 @@ export interface PartnerEmbedSession {
2996
3128
  components: string[];
2997
3129
  business_id: string;
2998
3130
  }
3131
+ /** 1.32.0 (00807): one of your businesses as you bill it on your own Stripe account. */
3132
+ export interface PartnerBusinessBilling {
3133
+ id: string;
3134
+ external_id: string | null;
3135
+ name: string;
3136
+ status: string;
3137
+ /** What you set for it; null is your default. */
3138
+ mode: "none" | "invoice" | "prepaid" | null;
3139
+ effective_mode: "none" | "invoice" | "prepaid";
3140
+ balance_cents: number;
3141
+ gift_left_cents: number;
3142
+ card: {
3143
+ brand: string | null;
3144
+ last4: string;
3145
+ } | null;
3146
+ customer: boolean;
3147
+ /** `off_reason`: why we turned it off (a decline, five reloads in a day, no card). */
3148
+ reload: {
3149
+ enabled: boolean;
3150
+ below_cents: number | null;
3151
+ amount_cents: number | null;
3152
+ off_reason: string | null;
3153
+ };
3154
+ /** A charge we could not make at Stripe, or a reload we stopped: yours to put right (`resolved` tries it again), not a payment it missed. */
3155
+ problem: {
3156
+ text: string;
3157
+ since: string | null;
3158
+ } | null;
3159
+ /** Suspended by us on your `auto_suspend`; its payment lifts it. */
3160
+ auto_suspended: boolean;
3161
+ /** It has not paid: a card payment Stripe gave up on, an emailed invoice past due by your `overdue_days`, a reload declined, or a dispute. `quiet` while you gave it time. */
3162
+ unpaid: {
3163
+ since: string;
3164
+ reason: string | null;
3165
+ charge_id: string | null;
3166
+ quiet: boolean;
3167
+ } | null;
3168
+ grace_until: string | null;
3169
+ }
3170
+ /** 1.32.0 (00807): your own Stripe account, how you bill by default, and each business you made. */
3171
+ export interface PartnerBilling {
3172
+ connected: boolean;
3173
+ account: {
3174
+ id: string;
3175
+ charges_enabled: boolean;
3176
+ details_submitted: boolean;
3177
+ due: number;
3178
+ connected_at: string;
3179
+ checked_at: string | null;
3180
+ } | null;
3181
+ connects: number;
3182
+ default_mode: "none" | "invoice" | "prepaid";
3183
+ auto_suspend: boolean;
3184
+ plan_name: string | null;
3185
+ days_until_due: number;
3186
+ /** Days past due before an emailed invoice counts as not paid. */
3187
+ overdue_days: number;
3188
+ plan: {
3189
+ name: string;
3190
+ monthly_cents: number | null;
3191
+ yearly_cents: number | null;
3192
+ interval: null;
3193
+ };
3194
+ businesses: PartnerBusinessBilling[];
3195
+ }
3196
+ /** 1.32.0 (00807): a month per business: billed, paid you, paid us for it, and your margin. */
3197
+ export interface PartnerBillingReport {
3198
+ month: string;
3199
+ currency: "usd";
3200
+ businesses: Array<{
3201
+ id: string;
3202
+ external_id: string | null;
3203
+ name: string;
3204
+ billed_cents: number;
3205
+ paid_cents: number;
3206
+ our_cents: number;
3207
+ margin_cents: number;
3208
+ partner_cents: number;
3209
+ to_bill_cents: number;
3210
+ }>;
3211
+ billed_cents: number;
3212
+ paid_cents: number;
3213
+ our_cents: number;
3214
+ margin_cents: number;
3215
+ }
2999
3216
  /** 00759: a business's gift credit after a change. */
3000
3217
  export interface PartnerGiftCredit {
3001
3218
  left_cents: number;
@@ -3014,15 +3231,20 @@ export interface PartnerUsage {
3014
3231
  item: string;
3015
3232
  draws: number;
3016
3233
  our_cents: number;
3234
+ public_cents: number;
3017
3235
  partner_cents: number;
3018
3236
  }>;
3019
3237
  our_cents: number;
3238
+ public_cents: number;
3020
3239
  partner_cents: number;
3021
3240
  gift_used_cents: number;
3022
3241
  /** Your prices, less the gift credit it spent: what is left for you to bill it. */
3023
3242
  to_bill_cents: number;
3024
3243
  }>;
3244
+ /** What we charged you: your own prices where your agreement sets them (00806), ours where it does not. */
3025
3245
  our_cents: number;
3246
+ /** 00806: what the same would have cost at our public prices. */
3247
+ public_cents: number;
3026
3248
  partner_cents: number;
3027
3249
  gift_used_cents: number;
3028
3250
  to_bill_cents: number;
@@ -3037,21 +3259,29 @@ export interface PartnerUsageLine {
3037
3259
  item: string;
3038
3260
  draws: number;
3039
3261
  our_cents: number;
3262
+ public_cents: number;
3040
3263
  partner_cents: number;
3041
3264
  }>;
3042
3265
  our_cents: number;
3266
+ /** 00806: what the same would have cost at our public prices. */
3267
+ public_cents: number;
3043
3268
  partner_cents: number;
3044
3269
  gift_used_cents: number;
3045
3270
  /** Your prices, less the gift credit it spent: what is left for you to bill it. */
3046
3271
  to_bill_cents: number;
3047
3272
  }
3048
- /** 00803: the two events only your partner endpoints hear (name them in `addWebhook`'s `events`, or take `"*"`). */
3273
+ /**
3274
+ * 00803: the two events only your partner endpoints hear. Only an endpoint
3275
+ * that names them in `addWebhook`'s (or `updateWebhook`'s) `events` is sent
3276
+ * them: `"*"` is every other event, but not these two (00805).
3277
+ */
3049
3278
  export type PartnerUsageEventName = "business.usage" | "partner.usage_closed";
3050
3279
  /**
3051
- * 00803: `business.usage`, the body a partner endpoint is sent as one of
3052
- * your businesses uses things: its month so far, at most once a minute per
3053
- * business. Each carries the whole month to date, so keep the latest
3054
- * (`occurred_at`); one that arrives late or twice changes nothing.
3280
+ * 00803: `business.usage`, the body a partner endpoint that names it is sent
3281
+ * (never one on `"*"` alone, 00805) as one of your businesses uses things:
3282
+ * its month so far, at most once a minute per business. Each carries the
3283
+ * whole month to date, so keep the latest (`occurred_at`); one that arrives
3284
+ * late or twice changes nothing.
3055
3285
  */
3056
3286
  export interface BusinessUsageEvent {
3057
3287
  event: "business.usage";
@@ -3069,7 +3299,8 @@ export interface BusinessUsageEvent {
3069
3299
  usage: PartnerUsageLine;
3070
3300
  }
3071
3301
  /**
3072
- * 00803: `partner.usage_closed`, sent once for each business in a month's
3302
+ * 00803: `partner.usage_closed`, sent to a partner endpoint that names it
3303
+ * (never one on `"*"` alone, 00805) once for each business in a month's
3073
3304
  * report, from a quarter of an hour into the 1st (UTC): its closed month,
3074
3305
  * and `partner`, the month's totals across your businesses, with
3075
3306
  * `businesses`, how many events this close sends. The same numbers
@@ -3227,7 +3458,7 @@ export declare class SignSealerPartner {
3227
3458
  /** 00759: your prices for it alone, over your default; null or {} takes them away. */
3228
3459
  prices?: PartnerPriceList | null;
3229
3460
  }): Promise<ManagedBusiness>;
3230
- /** 00759: your default prices to your businesses, and what each unit is. */
3461
+ /** 00759: your default prices to your businesses, and what each unit is; 00806: and what we charge you (`charged`). */
3231
3462
  prices(): Promise<PartnerPrices>;
3232
3463
  /** 00759: replace your default prices; `{}` takes them all away. Safe to retry. */
3233
3464
  setPrices(prices: PartnerPriceList): Promise<PartnerPrices>;
@@ -3247,7 +3478,10 @@ export declare class SignSealerPartner {
3247
3478
  * with a test key, your sandbox's.
3248
3479
  */
3249
3480
  webhooks(): Promise<PartnerWebhook[]>;
3250
- /** 00760: add an endpoint for every business you made. Its signing `secret` is in this answer only. Sent once. */
3481
+ /**
3482
+ * 00760: add an endpoint for every business you made. Its signing `secret` is in this answer only. Sent once.
3483
+ * `events` is `["*"]` when left out: every event but `business.usage` and `partner.usage_closed`, which come only by name (00805).
3484
+ */
3251
3485
  addWebhook(endpoint: {
3252
3486
  url: string;
3253
3487
  events?: string[];
@@ -3278,7 +3512,7 @@ export declare class SignSealerPartner {
3278
3512
  * for one of your users. It opens once, within five minutes: ask for it as
3279
3513
  * the page that frames it loads. Sent once. `components` are the screens:
3280
3514
  * `documents` (the default), `send` (00789), `templates` (00791), and
3281
- * `settings` and `texting` (00792). Mount it with `@signsealer/embed`.
3515
+ * `settings` and `texting` (00792), and 1.32.0's `billing` (00807). Mount it with `@signsealer/embed`.
3282
3516
  */
3283
3517
  embedSession(id: string, session: {
3284
3518
  user: {
@@ -3287,10 +3521,51 @@ export declare class SignSealerPartner {
3287
3521
  email?: string;
3288
3522
  role?: "admin" | "member";
3289
3523
  };
3290
- components?: Array<"documents" | "send" | "templates" | "settings" | "texting">;
3524
+ components?: Array<"documents" | "send" | "templates" | "settings" | "texting" | "billing">;
3291
3525
  }): Promise<PartnerEmbedSession>;
3292
3526
  /** 00759: a calendar month (YYYY-MM, this one when left out) per business, in your prices, with what to bill. */
3293
3527
  usage(month?: string): Promise<PartnerUsage>;
3528
+ /**
3529
+ * 1.32.0 (00807): billing your businesses on your own Stripe account: the
3530
+ * account (connected from your dashboard by its owner), how you bill by
3531
+ * default, and each business you made. Live keys only.
3532
+ */
3533
+ billing(): Promise<PartnerBilling>;
3534
+ /**
3535
+ * 1.32.0 (00807): how you bill by default (`none`, `invoice` or `prepaid`),
3536
+ * whether a business that does not pay is suspended without asking you,
3537
+ * your plan's name, and the days to pay an invoice sent to a business with
3538
+ * no card. Safe to retry.
3539
+ */
3540
+ updateBilling(changes: {
3541
+ default_mode?: "none" | "invoice" | "prepaid";
3542
+ auto_suspend?: boolean;
3543
+ plan_name?: string | null;
3544
+ days_until_due?: number;
3545
+ overdue_days?: number;
3546
+ }): Promise<PartnerBilling>;
3547
+ /**
3548
+ * 1.32.0 (00807): one business: how it pays (null for your default), a day
3549
+ * it has to pay by (`grace_until`), or its flag taken off (`resolved`).
3550
+ * Suspend it with `updateBusiness(id, { status: "suspended" })`. Safe to retry.
3551
+ */
3552
+ updateBusinessBilling(id: string, changes: {
3553
+ mode?: "none" | "invoice" | "prepaid" | null;
3554
+ grace_until?: string | null;
3555
+ resolved?: boolean;
3556
+ }): Promise<PartnerBusinessBilling>;
3557
+ /**
3558
+ * 1.32.0 (00807): credit for a business that has not paid: on its prepaid
3559
+ * credit when it pays ahead, as gift credit when it is invoiced. With an
3560
+ * `idempotencyKey` it is safe to retry; without one it is sent once.
3561
+ */
3562
+ creditBusiness(id: string, credit: {
3563
+ cents: number;
3564
+ note?: string;
3565
+ idempotencyKey?: string;
3566
+ }): Promise<Record<string, unknown>>;
3567
+ /** 1.32.0 (00807): a month (YYYY-MM, this one when left out) per business: billed, paid you, paid us for it, and your margin. */
3568
+ billingReport(month?: string): Promise<PartnerBillingReport>;
3294
3569
  /**
3295
3570
  * 00751: a client that acts for one of your businesses -- one you made,
3296
3571
  * or one that connected your app -- by its id or your own `external_id`.