@deliverd/sdk 0.14.0 → 0.16.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.
package/src/reports.ts CHANGED
@@ -10,6 +10,7 @@ import type {
10
10
  ReportData,
11
11
  ScheduleSummary,
12
12
  SendResult,
13
+ ShareOptions,
13
14
  UpdateReportInput,
14
15
  EvidencePack,
15
16
  } from "./types.js";
@@ -122,12 +123,28 @@ export class Reports {
122
123
  });
123
124
  }
124
125
 
125
- /** Grant people, teams or groups access. Filing is not access; this is. */
126
- async share(idOrSlug: string, audience: unknown, signal?: AbortSignal): Promise<unknown[]> {
126
+ /**
127
+ * Grant people, teams or groups access. Filing is not access; this is.
128
+ *
129
+ * `{ capability: "comment" }` lets them comment as well as read; leave it
130
+ * out for view. A signal in third place, as before options existed, still
131
+ * works.
132
+ */
133
+ async share(
134
+ idOrSlug: string,
135
+ audience: unknown,
136
+ options?: ShareOptions | AbortSignal,
137
+ signal?: AbortSignal
138
+ ): Promise<unknown[]> {
139
+ if (options instanceof AbortSignal) {
140
+ signal = options;
141
+ options = undefined;
142
+ }
143
+ const capability = options?.capability;
127
144
  const { granted } = await this.http.request<{ granted: unknown[] }>({
128
145
  method: "POST",
129
146
  path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
130
- body: { audience },
147
+ body: capability ? { audience, capability } : { audience },
131
148
  signal,
132
149
  });
133
150
  return granted;
package/src/types.ts CHANGED
@@ -436,12 +436,66 @@ export type Decision = {
436
436
  export interface ListApprovalsInput {
437
437
  status?: ApprovalStatus;
438
438
  externalId?: string;
439
+ /**
440
+ * The requests naming one person — a member's id or email, or an admitted
441
+ * guest's email. An approver's inbox, to render in your own product.
442
+ */
443
+ approver?: string;
439
444
  /** One page of this size. Leave it unset to get every row. */
440
445
  limit?: number;
441
446
  /** `nextCursor` from a previous page. Only meaningful with `limit`. */
442
447
  cursor?: string;
443
448
  }
444
449
 
450
+ /* ── Decision sessions ───────────────────────────────────────────────────── */
451
+
452
+ /**
453
+ * A page on which one approver decides one request, inside your product.
454
+ * `hosted` gives you a `url` to send them to; `embedded` gives you a
455
+ * `clientSecret` to mount with `https://deliverd.dev/elements/v1.js`.
456
+ */
457
+ export interface CreateDecisionSessionInput {
458
+ /** The approver, by email or user id. They must already be on the request. */
459
+ approver: string;
460
+ /** Defaults to `hosted`. */
461
+ mode?: "hosted" | "embedded";
462
+ /**
463
+ * Embedded only: the site that frames it, such as `https://app.example.com`.
464
+ * On the organisation's embedding allow-list, or `http://localhost` while
465
+ * you develop.
466
+ */
467
+ origin?: string;
468
+ /** Hosted only: where to send them afterwards. `deliverd_session` and `deliverd_decision` are added. */
469
+ returnUrl?: string;
470
+ /** Seconds, 60 to 86400. Never past the request's own deadline. Defaults to an hour. */
471
+ expiresIn?: number;
472
+ }
473
+
474
+ export type DecisionSessionStatus = "open" | "verified" | "complete" | "expired";
475
+
476
+ export interface DecisionSession {
477
+ id: string;
478
+ object: "decision_session";
479
+ approvalId: string;
480
+ approver: { type: "member" | "guest"; email: string };
481
+ mode: "hosted" | "embedded";
482
+ origin: string | null;
483
+ returnUrl: string | null;
484
+ /** The page, with the secret in it. Returned once, when the session is made. */
485
+ url?: string;
486
+ /** What `Deliverd.mountDecision` takes. Returned once, when the session is made. */
487
+ clientSecret?: string;
488
+ /** `verified` once the approver has confirmed who they are; `complete` once they have decided. */
489
+ status: DecisionSessionStatus;
490
+ decision: "approved" | "rejected" | "changes_requested" | null;
491
+ /** The request's own status, which another approver may have settled. */
492
+ approvalStatus: ApprovalStatus;
493
+ expiresAt: string;
494
+ verifiedAt: string | null;
495
+ completedAt: string | null;
496
+ createdAt: string;
497
+ }
498
+
445
499
  /* ── Reports ─────────────────────────────────────────────────────────────── */
446
500
 
447
501
  export interface InlineFile {
@@ -558,6 +612,18 @@ export interface SendResult {
558
612
  alreadyHadAccess: string[];
559
613
  }
560
614
 
615
+ /**
616
+ * What a share lets its audience do. `"view"` is the default.
617
+ *
618
+ * "Can manage", which lets someone share the report on, is not here: it is a
619
+ * person's decision, made in the app, and the API refuses it from a key.
620
+ */
621
+ export type ShareCapability = "view" | "comment";
622
+
623
+ export interface ShareOptions {
624
+ capability?: ShareCapability;
625
+ }
626
+
561
627
  /* ── Schedules ───────────────────────────────────────────────────────────── */
562
628
 
563
629
  /**
@@ -711,6 +777,92 @@ export interface WebhookEvent {
711
777
  data: Record<string, unknown>;
712
778
  }
713
779
 
780
+ /**
781
+ * How an endpoint's body is shaped: the signed JSON envelope, a Slack Block
782
+ * Kit message for an Incoming Webhook, or a Teams Adaptive Card for a
783
+ * Workflows webhook. The signature headers are sent with all three.
784
+ */
785
+ export type WebhookEndpointFormat = "json" | "slack" | "teams";
786
+
787
+ /** An organisation's webhook endpoint, as `deliverd.webhookEndpoints` reads it. Never its secret. */
788
+ export interface WebhookEndpoint {
789
+ id: string;
790
+ url: string;
791
+ description: string | null;
792
+ /** Empty means every event, including ones added later, except the opt-in ones. */
793
+ events: WebhookEventName[];
794
+ format: WebhookEndpointFormat;
795
+ enabled: boolean;
796
+ /** Consecutive failed deliveries. At twenty the endpoint is switched off. */
797
+ failureCount: number;
798
+ lastSuccessAt: string | null;
799
+ lastFailureAt: string | null;
800
+ lastError: string | null;
801
+ createdAt: string;
802
+ }
803
+
804
+ /**
805
+ * What `webhookEndpoints.create()` returns: the endpoint and its signing
806
+ * secret. **The only time the secret is returned** — no other call carries
807
+ * it, and it cannot be retrieved afterwards. Keep it with your receiver and
808
+ * pass it to `constructEvent()`.
809
+ */
810
+ export interface CreatedWebhookEndpoint {
811
+ id: string;
812
+ url: string;
813
+ description: string | null;
814
+ events: WebhookEventName[];
815
+ format: WebhookEndpointFormat;
816
+ enabled: boolean;
817
+ failureCount: number;
818
+ lastSuccessAt: string | null;
819
+ lastFailureAt: string | null;
820
+ lastError: string | null;
821
+ createdAt: string;
822
+ /** `dlvw_…`. Shown once. */
823
+ secret: string;
824
+ }
825
+
826
+ export interface CreateWebhookEndpointInput {
827
+ /** HTTPS, on a public host. */
828
+ url: string;
829
+ /** Leave it out, or send `[]`, for every event except the opt-in ones. */
830
+ events?: WebhookEventName[];
831
+ description?: string | null;
832
+ /** Default `"json"`. */
833
+ format?: WebhookEndpointFormat;
834
+ }
835
+
836
+ /** Only what you send changes; send at least one. The secret cannot be changed. */
837
+ export interface UpdateWebhookEndpointInput {
838
+ url?: string;
839
+ events?: WebhookEventName[];
840
+ description?: string | null;
841
+ format?: WebhookEndpointFormat;
842
+ /** Turning it back on clears its run of failures. */
843
+ enabled?: boolean;
844
+ }
845
+
846
+ export interface TestWebhookEndpointInput {
847
+ /** Default `"report.published"`. */
848
+ event?: WebhookEventName;
849
+ }
850
+
851
+ /** What the endpoint said to a test send. `delivered: false` is an answer, not an error. */
852
+ export interface WebhookTestResult {
853
+ delivered: boolean;
854
+ /** Null when it could not be reached. */
855
+ responseStatus: number | null;
856
+ error: string | null;
857
+ }
858
+
859
+ export interface ListWebhookEndpointsInput {
860
+ /** One page of this size. Leave it unset to get every endpoint. */
861
+ limit?: number;
862
+ /** `nextCursor` from a previous page. Only meaningful with `limit`. */
863
+ cursor?: string;
864
+ }
865
+
714
866
  /* ── Reviews ──────────────────────────────────────────────────────────────── */
715
867
 
716
868
  export type ReviewStatus =
@@ -0,0 +1,115 @@
1
+ import type { HttpClient } from "./http.js";
2
+ import { listOrCollect, type PageOf } from "./paging.js";
3
+ import type {
4
+ CreatedWebhookEndpoint,
5
+ CreateWebhookEndpointInput,
6
+ ListWebhookEndpointsInput,
7
+ TestWebhookEndpointInput,
8
+ UpdateWebhookEndpointInput,
9
+ WebhookEndpoint,
10
+ WebhookTestResult,
11
+ } from "./types.js";
12
+
13
+ /**
14
+ * The organisation's webhook endpoints: where its events are sent.
15
+ *
16
+ * ```ts
17
+ * const endpoint = await deliverd.webhookEndpoints.create({
18
+ * url: "https://hooks.example.com/deliverd",
19
+ * events: ["approval.approved", "approval.rejected"],
20
+ * });
21
+ * saveSecret(endpoint.secret); // returned this once, never again
22
+ * ```
23
+ *
24
+ * **Needs an administrator's key with `webhooks:manage`.** An endpoint
25
+ * receives every event in the organisation, so the API checks the key's
26
+ * holder is an owner or an administrator on every call, and refuses an agent
27
+ * key outright (`agent_not_permitted`) — reads included.
28
+ *
29
+ * Distinct from `deliverd.webhooks`, which verifies what arrives at an
30
+ * endpoint and makes no request at all.
31
+ */
32
+ export class WebhookEndpoints {
33
+ constructor(private readonly http: HttpClient) {}
34
+
35
+ /**
36
+ * Newest first. With no `limit` this is every endpoint; with a `limit` it is
37
+ * one page of that size, and `listPage` hands back the cursor to continue from.
38
+ */
39
+ async list(input: ListWebhookEndpointsInput = {}, signal?: AbortSignal): Promise<WebhookEndpoint[]> {
40
+ return listOrCollect(input, (q) => this.listPage({ ...input, ...q }, signal));
41
+ }
42
+
43
+ /** One page, and the cursor to continue from — null when it is the end. */
44
+ async listPage(
45
+ input: ListWebhookEndpointsInput = {},
46
+ signal?: AbortSignal
47
+ ): Promise<PageOf<WebhookEndpoint>> {
48
+ const { webhookEndpoints, nextCursor } = await this.http.request<{
49
+ webhookEndpoints: WebhookEndpoint[];
50
+ nextCursor: string | null;
51
+ }>({
52
+ method: "GET",
53
+ path: "/webhook-endpoints",
54
+ query: { limit: input.limit, cursor: input.cursor },
55
+ signal,
56
+ });
57
+ return { items: webhookEndpoints, nextCursor };
58
+ }
59
+
60
+ /**
61
+ * Add an endpoint. The result carries `secret`, **the only time it is
62
+ * returned**: keep it with whatever receives the events. A retried call
63
+ * replays this same response, secret included, rather than adding a second
64
+ * endpoint.
65
+ */
66
+ create(input: CreateWebhookEndpointInput, signal?: AbortSignal): Promise<CreatedWebhookEndpoint> {
67
+ return this.http.request({ method: "POST", path: "/webhook-endpoints", body: input, signal });
68
+ }
69
+
70
+ /** One endpoint, with its delivery health. Never its secret. */
71
+ get(id: string, signal?: AbortSignal): Promise<WebhookEndpoint> {
72
+ return this.http.request({
73
+ method: "GET",
74
+ path: `/webhook-endpoints/${encodeURIComponent(id)}`,
75
+ signal,
76
+ });
77
+ }
78
+
79
+ /**
80
+ * Change the address, events, description or format, or turn it off and on.
81
+ * Only what you send changes. Turning one back on clears its run of failures.
82
+ */
83
+ update(id: string, input: UpdateWebhookEndpointInput, signal?: AbortSignal): Promise<WebhookEndpoint> {
84
+ return this.http.request({
85
+ method: "PATCH",
86
+ path: `/webhook-endpoints/${encodeURIComponent(id)}`,
87
+ body: input,
88
+ signal,
89
+ });
90
+ }
91
+
92
+ /** Remove it, and its delivery log. `update(id, { enabled: false })` pauses it instead. */
93
+ delete(id: string, signal?: AbortSignal): Promise<void> {
94
+ return this.http.request({
95
+ method: "DELETE",
96
+ path: `/webhook-endpoints/${encodeURIComponent(id)}`,
97
+ signal,
98
+ });
99
+ }
100
+
101
+ /**
102
+ * Send it one event now — `"test": true`, obviously fake ids — and get back
103
+ * what it answered. Never retried, and never counted toward switching the
104
+ * endpoint off. `delivered: false` is an answer about the endpoint; this
105
+ * throws only when the call itself is refused.
106
+ */
107
+ test(id: string, input: TestWebhookEndpointInput = {}, signal?: AbortSignal): Promise<WebhookTestResult> {
108
+ return this.http.request({
109
+ method: "POST",
110
+ path: `/webhook-endpoints/${encodeURIComponent(id)}/test`,
111
+ body: input,
112
+ signal,
113
+ });
114
+ }
115
+ }