@signsealer/sdk 1.28.0 → 1.31.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.
@@ -411,6 +411,59 @@ export interface TemplateTranslation {
411
411
  consent_text: string | null;
412
412
  body_sha256: string;
413
413
  ready_at: string;
414
+ /** 1.29.0: a translated PDF (00798): its own file, by its fingerprint. */
415
+ pdf?: TranslationPdfFile;
416
+ /** 1.29.0: a translated PDF's boxes on its own pages, by the question's key. */
417
+ places?: Record<string, TranslationPlace>;
418
+ }
419
+ /** A box on a page (1.29.0): `x`, `y`, `w`, `h` as fractions of the page as a reader sees it, from its top-left. */
420
+ export interface TranslationPlace {
421
+ page: number;
422
+ x: number;
423
+ y: number;
424
+ w: number;
425
+ h: number;
426
+ }
427
+ /** The file of a translated PDF, as the record names it (1.29.0). */
428
+ export interface TranslationPdfFile {
429
+ sha256: string;
430
+ pages: number;
431
+ name: string | null;
432
+ }
433
+ /** A translated PDF of a version in a language, being placed or in use (1.29.0). */
434
+ export interface PdfTranslationView {
435
+ id: string;
436
+ template_id: string;
437
+ language: string;
438
+ status: "draft" | "ready";
439
+ title: string;
440
+ fields: Record<string, TranslatedField>;
441
+ consent_text: string | null;
442
+ places: Record<string, TranslationPlace>;
443
+ body_sha256: string;
444
+ ready_at: string | null;
445
+ pdf: {
446
+ sha256: string;
447
+ page_count: number;
448
+ pages: Array<{
449
+ n: number;
450
+ width: number;
451
+ height: number;
452
+ }>;
453
+ drawn: number;
454
+ original_name: string | null;
455
+ uploaded_at: string;
456
+ } | null;
457
+ /** For a draft: what stands in the way of using it, in words; null when nothing does. */
458
+ problem: string | null;
459
+ }
460
+ /** What `pdfTranslation` answers (1.29.0): the draft being placed and the one in use. */
461
+ export interface PdfTranslationState {
462
+ template_id: string;
463
+ version: number;
464
+ language: string;
465
+ draft: PdfTranslationView | null;
466
+ ready: PdfTranslationView | null;
414
467
  }
415
468
  /** What `templateTranslations` answers (1.27.0). */
416
469
  export interface TemplateTranslations {
@@ -437,6 +490,17 @@ export interface TemplateTranslations {
437
490
  made_by: string | null;
438
491
  /** Still has exactly this version's blanks and questions. */
439
492
  fits: boolean;
493
+ /** 1.29.0: a translated PDF's own file. */
494
+ pdf?: TranslationPdfFile;
495
+ }>;
496
+ /** 1.29.0: on a PDF template, the translated PDFs of this version still being placed, each with what stands in its way. */
497
+ drafts?: Array<{
498
+ id: string;
499
+ language: string;
500
+ language_name: string;
501
+ language_english: string;
502
+ uploaded_at: string | null;
503
+ problem: string | null;
440
504
  }>;
441
505
  /** The languages one may be written in. */
442
506
  languages: Array<{
@@ -1192,7 +1256,7 @@ export interface ClientOptions {
1192
1256
  userAgent?: string;
1193
1257
  }
1194
1258
  /** This package's version, as `package.json` has it; `tests/sdk.ts` holds the two together. */
1195
- export declare const SDK_VERSION = "1.28.0";
1259
+ export declare const SDK_VERSION = "1.31.0";
1196
1260
  /** What a client built with a secret key in a web page throws (1.26.0). */
1197
1261
  export declare const KEY_IN_PAGE_MESSAGE: string;
1198
1262
  export declare class SignSealer {
@@ -1336,6 +1400,50 @@ export declare class SignSealer {
1336
1400
  language: string;
1337
1401
  withdrawn: boolean;
1338
1402
  }>;
1403
+ /**
1404
+ * Where an uploaded PDF template version's translated PDF in a language
1405
+ * stands (1.29.0): the draft being placed and the one in use.
1406
+ */
1407
+ pdfTranslation(id: string, language: string): Promise<PdfTranslationState>;
1408
+ /**
1409
+ * Upload the business's own translated PDF of an uploaded PDF template's
1410
+ * version (1.29.0), as the draft for its language: read and sanitised as
1411
+ * any PDF template's file is, its pages drawn, its boxes starting where
1412
+ * the original has them. Its page count may differ from the original's.
1413
+ */
1414
+ uploadPdfTranslation(id: string, language: string, pdf: {
1415
+ filename: string;
1416
+ content_base64: string;
1417
+ }): Promise<PdfTranslationState & {
1418
+ removed: string[];
1419
+ }>;
1420
+ /**
1421
+ * Save the translated PDF's words and boxes and use it (1.29.0), replacing
1422
+ * the one in use. Refused with 422, naming each box still to place and each
1423
+ * that should not be there, unless it matches the original field for field.
1424
+ * `use: false` saves the draft without using it.
1425
+ */
1426
+ savePdfTranslation(id: string, language: string, input: {
1427
+ title: string;
1428
+ fields?: Record<string, TranslatedField>;
1429
+ consent_text?: string | null;
1430
+ places: Record<string, TranslationPlace>;
1431
+ use?: boolean;
1432
+ }): Promise<TemplateTranslation | PdfTranslationState>;
1433
+ /** One page of a translated PDF as PNG bytes (1.29.0): the draft's while one is being placed, else the one in use. */
1434
+ pdfTranslationPage(id: string, language: string, page: number): Promise<{
1435
+ page: number;
1436
+ width: number;
1437
+ height: number;
1438
+ contentType: string;
1439
+ bytes: Uint8Array<ArrayBufferLike>;
1440
+ }>;
1441
+ /** Discard the translated PDF being placed in a language (1.29.0); the one in use stays. */
1442
+ discardPdfTranslation(id: string, language: string): Promise<{
1443
+ template_id: string;
1444
+ language: string;
1445
+ discarded: boolean;
1446
+ }>;
1339
1447
  /**
1340
1448
  * The settings a template's code carries to every version (1.6.0).
1341
1449
  * `resign: true` asks everybody who signed an older version to sign the
@@ -1981,6 +2089,31 @@ export declare class SignSealer {
1981
2089
  report_id: string;
1982
2090
  device_id: string;
1983
2091
  }>;
2092
+ /**
2093
+ * A test key (`mk_test_`) for the business's sandbox (00802), minted with a
2094
+ * live key that has `signing:sandbox`; the first one makes the sandbox.
2095
+ * `key` is in this answer only: a repeat of the same call, as a retry
2096
+ * after a lost answer is, has it null and `secrets_redacted`. Its `scopes`
2097
+ * are no more than this key's own (403 otherwise), never
2098
+ * `signing:device`. A test key cannot mint one (403).
2099
+ */
2100
+ mintTestKey(input: {
2101
+ label: string;
2102
+ scopes: string[];
2103
+ expires_at?: string;
2104
+ }, idempotencyKey?: string): Promise<TestKey>;
2105
+ /**
2106
+ * Start the sandbox clean (00802): every document in it is deleted, with
2107
+ * its evidence, and its templates, forms, people and packets; the live
2108
+ * account's published templates and active forms are copied in again.
2109
+ * Its test keys, webhook endpoints and tablets are kept, each tablet given
2110
+ * back its forms. With a test key,
2111
+ * its own sandbox; with a live key, the business's -- never the live
2112
+ * account. Needs `signing:sandbox`. Twenty an hour per business.
2113
+ */
2114
+ resetSandbox(input?: {
2115
+ reason?: string;
2116
+ }, idempotencyKey?: string): Promise<SandboxReset>;
1984
2117
  /**
1985
2118
  * The business's own applications whose servers vouch for their people's
1986
2119
  * approvals, each with its public keys (00684). Needs `signing:applications`.
@@ -2820,10 +2953,56 @@ export interface PartnerPriceList {
2820
2953
  id_check?: number;
2821
2954
  markup_bp?: number;
2822
2955
  }
2823
- /** 00759: your price list, and what each unit is. */
2956
+ /**
2957
+ * 00806: what we charge you for one item today: your own price where your
2958
+ * agreement with us sets one (`deal`, from `from` to `until`, the last day it
2959
+ * applies), our public price where it does not. In cents; a metered public
2960
+ * price may be a fraction of one, and null is an item not sold yet.
2961
+ */
2962
+ export interface PartnerChargedItem {
2963
+ item: string;
2964
+ label: string;
2965
+ /** Our public price for one, for a business starting today. */
2966
+ public_cents: number | null;
2967
+ /** The lowest and highest across the versions of our prices your businesses are on (a business keeps its version until its renewal after notice). */
2968
+ public_low: number | null;
2969
+ public_high: number | null;
2970
+ /** What we charge you for one, for a business starting today. */
2971
+ cents: number | null;
2972
+ cents_low: number | null;
2973
+ cents_high: number | null;
2974
+ deal: boolean;
2975
+ from: string | null;
2976
+ until: string | null;
2977
+ }
2978
+ /** 00806: a day ahead when what we charge you for an item changes, and to what. */
2979
+ export interface PartnerScheduledPrice {
2980
+ item: string;
2981
+ label: string;
2982
+ /** The first day (UTC) of the new price. */
2983
+ from: string;
2984
+ cents: number | null;
2985
+ public_cents: number | null;
2986
+ deal: boolean;
2987
+ /** A rise: where the email telling it stands. It comes in 30 full days after that email is sent, and not before `from`. */
2988
+ notice?: {
2989
+ state: "waiting" | "sent" | "in_force" | "undelivered";
2990
+ sent_at: string | null;
2991
+ in_force_from: string | null;
2992
+ } | null;
2993
+ }
2994
+ /** 00806: what we charge you, today and next. A price that goes up is told to your owner thirty days before (`notice_days`). */
2995
+ export interface PartnerCharged {
2996
+ as_of: string;
2997
+ notice_days: number;
2998
+ items: PartnerChargedItem[];
2999
+ scheduled: PartnerScheduledPrice[];
3000
+ }
3001
+ /** 00759: your price list, and what each unit is; 00806: and what we charge you. */
2824
3002
  export interface PartnerPrices {
2825
3003
  prices: PartnerPriceList;
2826
3004
  units: Record<string, string>;
3005
+ charged: PartnerCharged;
2827
3006
  }
2828
3007
  /** 00760: one of your webhook endpoints, copied onto every business you made (of its mode). */
2829
3008
  export interface PartnerWebhook {
@@ -2881,19 +3060,103 @@ export interface PartnerUsage {
2881
3060
  item: string;
2882
3061
  draws: number;
2883
3062
  our_cents: number;
3063
+ public_cents: number;
2884
3064
  partner_cents: number;
2885
3065
  }>;
2886
3066
  our_cents: number;
3067
+ public_cents: number;
2887
3068
  partner_cents: number;
2888
3069
  gift_used_cents: number;
2889
3070
  /** Your prices, less the gift credit it spent: what is left for you to bill it. */
2890
3071
  to_bill_cents: number;
2891
3072
  }>;
3073
+ /** What we charged you: your own prices where your agreement sets them (00806), ours where it does not. */
2892
3074
  our_cents: number;
3075
+ /** 00806: what the same would have cost at our public prices. */
3076
+ public_cents: number;
2893
3077
  partner_cents: number;
2894
3078
  gift_used_cents: number;
2895
3079
  to_bill_cents: number;
2896
3080
  }
3081
+ /**
3082
+ * 00803: one business's line of `usage(month)`, as the usage events carry it:
3083
+ * the same numbers, without the business's name (the delivery's
3084
+ * `business_id` and `external_id` say whose it is).
3085
+ */
3086
+ export interface PartnerUsageLine {
3087
+ items: Array<{
3088
+ item: string;
3089
+ draws: number;
3090
+ our_cents: number;
3091
+ public_cents: number;
3092
+ partner_cents: number;
3093
+ }>;
3094
+ our_cents: number;
3095
+ /** 00806: what the same would have cost at our public prices. */
3096
+ public_cents: number;
3097
+ partner_cents: number;
3098
+ gift_used_cents: number;
3099
+ /** Your prices, less the gift credit it spent: what is left for you to bill it. */
3100
+ to_bill_cents: number;
3101
+ }
3102
+ /**
3103
+ * 00803: the two events only your partner endpoints hear. Only an endpoint
3104
+ * that names them in `addWebhook`'s (or `updateWebhook`'s) `events` is sent
3105
+ * them: `"*"` is every other event, but not these two (00805).
3106
+ */
3107
+ export type PartnerUsageEventName = "business.usage" | "partner.usage_closed";
3108
+ /**
3109
+ * 00803: `business.usage`, the body a partner endpoint that names it is sent
3110
+ * (never one on `"*"` alone, 00805) as one of your businesses uses things:
3111
+ * its month so far, at most once a minute per business. Each carries the
3112
+ * whole month to date, so keep the latest (`occurred_at`); one that arrives
3113
+ * late or twice changes nothing.
3114
+ */
3115
+ export interface BusinessUsageEvent {
3116
+ event: "business.usage";
3117
+ /**
3118
+ * What to dedupe on: `<business id>:<month>:<time>`, the same on every
3119
+ * retry and replay of this event and different for any other.
3120
+ */
3121
+ key: string;
3122
+ occurred_at: string;
3123
+ tenant_id: string;
3124
+ business_id: string;
3125
+ external_id: string | null;
3126
+ /** YYYY-MM, UTC. */
3127
+ month: string;
3128
+ usage: PartnerUsageLine;
3129
+ }
3130
+ /**
3131
+ * 00803: `partner.usage_closed`, sent to a partner endpoint that names it
3132
+ * (never one on `"*"` alone, 00805) once for each business in a month's
3133
+ * report, from a quarter of an hour into the 1st (UTC): its closed month,
3134
+ * and `partner`, the month's totals across your businesses, with
3135
+ * `businesses`, how many events this close sends. The same numbers
3136
+ * `usage(month)` answers.
3137
+ */
3138
+ export interface PartnerUsageClosedEvent {
3139
+ event: "partner.usage_closed";
3140
+ /**
3141
+ * What to dedupe on: `<your partner id>:<month>:<business id>`, one for
3142
+ * each business and month, the same on every retry and replay.
3143
+ */
3144
+ key: string;
3145
+ occurred_at: string;
3146
+ tenant_id: string;
3147
+ business_id: string;
3148
+ external_id: string | null;
3149
+ /** YYYY-MM, UTC. */
3150
+ month: string;
3151
+ usage: PartnerUsageLine;
3152
+ partner: {
3153
+ businesses: number;
3154
+ our_cents: number;
3155
+ partner_cents: number;
3156
+ gift_used_cents: number;
3157
+ to_bill_cents: number;
3158
+ };
3159
+ }
2897
3160
  /** 00752: the prepaid balance your businesses draw on. */
2898
3161
  export interface PartnerBalance {
2899
3162
  balance_cents: number;
@@ -3024,7 +3287,7 @@ export declare class SignSealerPartner {
3024
3287
  /** 00759: your prices for it alone, over your default; null or {} takes them away. */
3025
3288
  prices?: PartnerPriceList | null;
3026
3289
  }): Promise<ManagedBusiness>;
3027
- /** 00759: your default prices to your businesses, and what each unit is. */
3290
+ /** 00759: your default prices to your businesses, and what each unit is; 00806: and what we charge you (`charged`). */
3028
3291
  prices(): Promise<PartnerPrices>;
3029
3292
  /** 00759: replace your default prices; `{}` takes them all away. Safe to retry. */
3030
3293
  setPrices(prices: PartnerPriceList): Promise<PartnerPrices>;
@@ -3044,7 +3307,10 @@ export declare class SignSealerPartner {
3044
3307
  * with a test key, your sandbox's.
3045
3308
  */
3046
3309
  webhooks(): Promise<PartnerWebhook[]>;
3047
- /** 00760: add an endpoint for every business you made. Its signing `secret` is in this answer only. Sent once. */
3310
+ /**
3311
+ * 00760: add an endpoint for every business you made. Its signing `secret` is in this answer only. Sent once.
3312
+ * `events` is `["*"]` when left out: every event but `business.usage` and `partner.usage_closed`, which come only by name (00805).
3313
+ */
3048
3314
  addWebhook(endpoint: {
3049
3315
  url: string;
3050
3316
  events?: string[];
@@ -3401,6 +3667,34 @@ export interface SigningApplicationKey {
3401
3667
  revoked_at: string | null;
3402
3668
  revoked_reason: string | null;
3403
3669
  }
3670
+ /** A test key, minted over the API (1.30.0). `key` is shown once: null on a repeat of the same call. */
3671
+ export interface TestKey {
3672
+ id: string;
3673
+ key: string | null;
3674
+ /** How the dashboard lists it: `mk_test_` and eight characters. */
3675
+ prefix: string;
3676
+ label: string;
3677
+ scopes: string[];
3678
+ expires_at: string | null;
3679
+ /** The sandbox it acts on: the business's twin, where nothing is sent to anybody or billed. */
3680
+ sandbox_id: string;
3681
+ redacted?: true;
3682
+ secrets_redacted?: true;
3683
+ }
3684
+ /** What a reset of the sandbox deleted, and copied in again from the live account (1.30.0). */
3685
+ export interface SandboxReset {
3686
+ sandbox_id: string;
3687
+ reset_at: string;
3688
+ deleted: {
3689
+ documents: number;
3690
+ templates: number;
3691
+ forms: number;
3692
+ };
3693
+ copied: {
3694
+ templates: number;
3695
+ forms: number;
3696
+ };
3697
+ }
3404
3698
  /** A business's own application, registered to vouch for its people (00684). */
3405
3699
  export interface SigningApplication {
3406
3700
  id: string;