degroshi 0.0.1 → 1.0.0-beta.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.
Files changed (72) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/LICENSE +3 -4
  3. package/NOTICE +30 -4
  4. package/README.md +124 -5
  5. package/dist/client.d.ts +140 -0
  6. package/dist/client.js +171 -0
  7. package/dist/client.js.map +1 -0
  8. package/dist/errors.d.ts +56 -0
  9. package/dist/errors.js +103 -0
  10. package/dist/errors.js.map +1 -0
  11. package/dist/generated/client/client.gen.d.ts +2 -0
  12. package/dist/generated/client/client.gen.js +217 -0
  13. package/dist/generated/client/client.gen.js.map +1 -0
  14. package/dist/generated/client/index.d.ts +10 -0
  15. package/dist/generated/client/index.js +7 -0
  16. package/dist/generated/client/index.js.map +1 -0
  17. package/dist/generated/client/types.gen.d.ts +120 -0
  18. package/dist/generated/client/types.gen.js +3 -0
  19. package/dist/generated/client/types.gen.js.map +1 -0
  20. package/dist/generated/client/utils.gen.d.ts +37 -0
  21. package/dist/generated/client/utils.gen.js +229 -0
  22. package/dist/generated/client/utils.gen.js.map +1 -0
  23. package/dist/generated/client.gen.d.ts +12 -0
  24. package/dist/generated/client.gen.js +4 -0
  25. package/dist/generated/client.gen.js.map +1 -0
  26. package/dist/generated/core/auth.gen.d.ts +25 -0
  27. package/dist/generated/core/auth.gen.js +15 -0
  28. package/dist/generated/core/auth.gen.js.map +1 -0
  29. package/dist/generated/core/bodySerializer.gen.d.ts +25 -0
  30. package/dist/generated/core/bodySerializer.gen.js +58 -0
  31. package/dist/generated/core/bodySerializer.gen.js.map +1 -0
  32. package/dist/generated/core/params.gen.d.ts +43 -0
  33. package/dist/generated/core/params.gen.js +110 -0
  34. package/dist/generated/core/params.gen.js.map +1 -0
  35. package/dist/generated/core/pathSerializer.gen.d.ts +33 -0
  36. package/dist/generated/core/pathSerializer.gen.js +107 -0
  37. package/dist/generated/core/pathSerializer.gen.js.map +1 -0
  38. package/dist/generated/core/queryKeySerializer.gen.d.ts +18 -0
  39. package/dist/generated/core/queryKeySerializer.gen.js +93 -0
  40. package/dist/generated/core/queryKeySerializer.gen.js.map +1 -0
  41. package/dist/generated/core/serverSentEvents.gen.d.ts +71 -0
  42. package/dist/generated/core/serverSentEvents.gen.js +133 -0
  43. package/dist/generated/core/serverSentEvents.gen.js.map +1 -0
  44. package/dist/generated/core/types.gen.d.ts +83 -0
  45. package/dist/generated/core/types.gen.js +3 -0
  46. package/dist/generated/core/types.gen.js.map +1 -0
  47. package/dist/generated/core/utils.gen.d.ts +19 -0
  48. package/dist/generated/core/utils.gen.js +88 -0
  49. package/dist/generated/core/utils.gen.js.map +1 -0
  50. package/dist/generated/index.d.ts +2 -0
  51. package/dist/generated/index.js +3 -0
  52. package/dist/generated/index.js.map +1 -0
  53. package/dist/generated/sdk.gen.d.ts +231 -0
  54. package/dist/generated/sdk.gen.js +393 -0
  55. package/dist/generated/sdk.gen.js.map +1 -0
  56. package/dist/generated/types.gen.d.ts +4416 -0
  57. package/dist/generated/types.gen.js +3 -0
  58. package/dist/generated/types.gen.js.map +1 -0
  59. package/dist/index.d.ts +6 -0
  60. package/dist/index.js +6 -0
  61. package/dist/index.js.map +1 -0
  62. package/dist/retry.d.ts +22 -0
  63. package/dist/retry.js +51 -0
  64. package/dist/retry.js.map +1 -0
  65. package/dist/version.d.ts +2 -0
  66. package/dist/version.js +4 -0
  67. package/dist/version.js.map +1 -0
  68. package/dist/webhooks.d.ts +24 -0
  69. package/dist/webhooks.js +57 -0
  70. package/dist/webhooks.js.map +1 -0
  71. package/package.json +55 -8
  72. package/index.js +0 -5
package/CHANGELOG.md ADDED
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ Versions follow semver; the major version follows the API's (v1). The API part of each entry comes from comparing the
4
+ public spec with the last release (oasdiff); the SDK part lists SDK-only changes.
5
+
6
+ ## 1.0.0-beta.0 (2026-11-12)
7
+
8
+ ### API
9
+
10
+ - Every operation and webhook of the public API v1: accounts, transactions, categories, budgets, recurring
11
+ payments, analytics, custom sources and events.
12
+
13
+ ### SDK
14
+
15
+ - `new Degroshi({ apiKey })` with resource methods, typed errors, retries with backoff for requests that are safe to
16
+ repeat, an `Idempotency-Key` on creates, page and cursor iterators, and `webhooks.verify`.
package/LICENSE CHANGED
@@ -1,5 +1,4 @@
1
-
2
- Apache License
1
+ Apache License
3
2
  Version 2.0, January 2004
4
3
  http://www.apache.org/licenses/
5
4
 
@@ -179,7 +178,7 @@
179
178
  APPENDIX: How to apply the Apache License to your work.
180
179
 
181
180
  To apply the Apache License to your work, attach the following
182
- boilerplate notice, with the fields enclosed by brackets "[]"
181
+ boilerplate notice, with the fields enclosed by brackets "{}"
183
182
  replaced with your own identifying information. (Don't include
184
183
  the brackets!) The text should be enclosed in the appropriate
185
184
  comment syntax for the file format. We also recommend that a
@@ -187,7 +186,7 @@
187
186
  same "printed page" as the copyright notice for easier
188
187
  identification within third-party archives.
189
188
 
190
- Copyright [yyyy] [name of copyright owner]
189
+ Copyright 2026 Degroshi
191
190
 
192
191
  Licensed under the Apache License, Version 2.0 (the "License");
193
192
  you may not use this file except in compliance with the License.
package/NOTICE CHANGED
@@ -1,6 +1,32 @@
1
- Degroshi SDK
1
+ Degroshi SDK for JavaScript and TypeScript
2
2
  Copyright 2026 Degroshi
3
3
 
4
- This product is licensed under the Apache License, Version 2.0.
5
- The Degroshi name and logo are not licensed under it and may not be used
6
- to endorse or promote products without written permission.
4
+ This product is licensed under the Apache License, Version 2.0 (see LICENSE).
5
+
6
+ The "Degroshi" and "деГроші" names and logos are trademarks of Degroshi. They are not licensed under the Apache
7
+ License (see its section 6) and may not be used to endorse or promote products derived from this software.
8
+
9
+ This product includes the HTTP client generated by @hey-api/openapi-ts (src/generated/client and src/generated/core),
10
+ which is licensed under the MIT License:
11
+
12
+ MIT License
13
+
14
+ Copyright (c) Hey API
15
+
16
+ Permission is hereby granted, free of charge, to any person obtaining a copy
17
+ of this software and associated documentation files (the "Software"), to deal
18
+ in the Software without restriction, including without limitation the rights
19
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
20
+ copies of the Software, and to permit persons to whom the Software is
21
+ furnished to do so, subject to the following conditions:
22
+
23
+ The above copyright notice and this permission notice shall be included in all
24
+ copies or substantial portions of the Software.
25
+
26
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
27
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
28
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
29
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
30
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
31
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
32
+ SOFTWARE.
package/README.md CHANGED
@@ -1,9 +1,128 @@
1
- # degroshi
1
+ # Degroshi for JavaScript and TypeScript
2
2
 
3
- The official Degroshi SDK for JavaScript and TypeScript is coming soon.
3
+ [![npm](https://img.shields.io/npm/v/degroshi)](https://www.npmjs.com/package/degroshi)
4
+ [![CI](https://github.com/degroshi/degroshi-js/actions/workflows/ci.yml/badge.svg)](https://github.com/degroshi/degroshi-js/actions/workflows/ci.yml)
5
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
4
6
 
5
- Until it's released, use the Degroshi API directly with a personal API key: [docs.degroshi.com/en/developers](https://docs.degroshi.com/en/developers).
7
+ The official SDK for the [Degroshi API](https://docs.degroshi.com/en/developers). It has typed methods for accounts,
8
+ transactions, categories, budgets, recurring payments, analytics, custom sources and events. Retries are safe to
9
+ repeat, and webhook signatures are checked for you. It has no runtime dependencies and runs on Node 20+, Bun, Deno,
10
+ browsers and edge runtimes.
6
11
 
7
- Security reports: [security@degroshi.com](mailto:security@degroshi.com). Everything else: [support@degroshi.com](mailto:support@degroshi.com).
12
+ ## Install
8
13
 
9
- Licensed under the Apache License, Version 2.0.
14
+ ```sh
15
+ npm i degroshi
16
+ ```
17
+
18
+ ## Authenticate
19
+
20
+ Create a personal access token in Degroshi under "Settings" › "For developers", and keep it on a server: anyone who
21
+ reads it can use it. The client takes it as `apiKey`, or reads `DEGROSHI_API_KEY` from the environment.
22
+
23
+ ```ts
24
+ import { Degroshi } from "degroshi"
25
+
26
+ const degroshi = new Degroshi({ apiKey: process.env.DEGROSHI_API_KEY })
27
+
28
+ const accounts = await degroshi.accounts.list()
29
+ ```
30
+
31
+ A token that reaches several spaces needs the space too: `new Degroshi({ apiKey, spaceId })`. The IDs are under
32
+ "Settings" › "For developers" › "Space IDs".
33
+
34
+ ## Pagination
35
+
36
+ `transactions.list()` returns one page: `data` and `meta` (`page`, `per_page`, `total`, `has_next`).
37
+ `transactions.iterate()` walks every page for you:
38
+
39
+ ```ts
40
+ for await (const transaction of degroshi.transactions.iterate({ from_date: "2026-11-01" })) {
41
+ console.log(transaction.transaction_date, transaction.direction, transaction.amount)
42
+ }
43
+ ```
44
+
45
+ Lists that use cursors (`sources.iteratePushed`, `events.iterate`) follow `next_cursor` the same way.
46
+
47
+ ## Money
48
+
49
+ Amounts are strings, exactly as the API sends them (`"642.30"`), so no precision is lost. Don't turn them into
50
+ numbers to add them up: use a decimal library or your database. Totals across currencies come from the API's
51
+ analytics, already converted.
52
+
53
+ ## Write safely
54
+
55
+ `transactions.create`, `sources.create`, `sources.pushTransactions` and `sources.pushBalances` send an
56
+ `Idempotency-Key`, so a retry after a dropped connection returns the first answer instead of writing twice. Pass your
57
+ own key to retry safely across restarts:
58
+
59
+ ```ts
60
+ await degroshi.transactions.create(
61
+ { account_id: accountId, amount: "120.00", type: "expense", transaction_date: new Date().toISOString() },
62
+ { idempotencyKey: `order-${orderId}` }
63
+ )
64
+ ```
65
+
66
+ Edits take the row's `version` as `ifMatch`. If someone changed the row in the meantime, the API answers 412 and the
67
+ client throws a `ConflictError`.
68
+
69
+ ## Errors
70
+
71
+ Every API error is a `DegroshiError` with `status`, `code` (for example `TXN_ACCOUNT_CONNECTED`), `details` and
72
+ `correlationId`; include the `correlationId` when you contact support. Subclasses name the common cases:
73
+ `BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`,
74
+ `UnprocessableEntityError`, `RateLimitError` and `InternalServerError`. A network failure is an `ApiConnectionError`,
75
+ and a timeout is an `ApiTimeoutError`.
76
+
77
+ ```ts
78
+ import { NotFoundError } from "degroshi"
79
+
80
+ try {
81
+ await degroshi.accounts.get(accountId)
82
+ } catch (error) {
83
+ if (error instanceof NotFoundError) console.log("No such account in this space")
84
+ else throw error
85
+ }
86
+ ```
87
+
88
+ Requests that are safe to repeat are retried on network failures, 408, 429, 500, 502, 503 and 504, with backoff and
89
+ respecting `Retry-After`. `maxRetries` sets how many times (default 2), and `timeoutMs` how long one try may take (default
90
+ 60 000).
91
+
92
+ ## Webhooks
93
+
94
+ Check every delivery before you trust it. Pass the raw body, before any JSON parsing:
95
+
96
+ ```ts
97
+ import { verifyWebhook } from "degroshi"
98
+
99
+ const event = await verifyWebhook(rawBody, request.headers.get("Degroshi-Signature"), process.env.WEBHOOK_SECRET!)
100
+ if (event.type === "transaction.created") console.log(event.data.object.amount)
101
+ ```
102
+
103
+ `verifyWebhook` throws a `WebhookVerificationError` with a `reason` for a wrong signature, a malformed header or a
104
+ signature older than five minutes. While you rotate a secret, either secret passes. `degroshi.webhooks.verify` does the
105
+ same.
106
+
107
+ `degroshi.events.iterate()` reads the space's events of the last 30 days, in the same shape as webhook deliveries, so
108
+ you can catch up after downtime.
109
+
110
+ ## Documentation
111
+
112
+ - [Developer guide](https://docs.degroshi.com/en/developers): tokens, spaces, limits and errors.
113
+ - [API reference](https://docs.degroshi.com/en/developers/api/me/list-my-spaces): every endpoint and its fields.
114
+ - [Webhooks](https://docs.degroshi.com/en/developers/webhooks): events, signatures and retries.
115
+
116
+ ## Versions
117
+
118
+ The SDK follows semver, and its major version follows the API's (v1). A minor release adds operations or fields, and
119
+ a patch release fixes the SDK. Breaking changes come only with a new major version. See [CHANGELOG.md](CHANGELOG.md).
120
+
121
+ ## Contributing and security
122
+
123
+ Issues are welcome. The SDK is generated from the public API spec, so pull requests aren't merged here directly: see
124
+ [CONTRIBUTING.md](CONTRIBUTING.md). Report a vulnerability privately, as [SECURITY.md](SECURITY.md) explains.
125
+
126
+ ## Licence
127
+
128
+ Apache-2.0: see [LICENSE](LICENSE) and [NOTICE](NOTICE). The Degroshi name and logo aren't licensed.
@@ -0,0 +1,140 @@
1
+ import { type Client } from "./generated/client/index.js";
2
+ import type * as T from "./generated/types.gen.js";
3
+ import { DegroshiError } from "./errors.js";
4
+ import { type FetchFn } from "./retry.js";
5
+ import { type VerifyOptions, type WebhookEvent } from "./webhooks.js";
6
+ export interface DegroshiOptions {
7
+ /** A personal access token (dg_pat_…), sent as X-API-Key. Default: the DEGROSHI_API_KEY environment variable. */
8
+ apiKey?: string;
9
+ /** The space to act in (X-Space-ID); optional for a token bound to one space. */
10
+ spaceId?: string;
11
+ /** Default: https://api.degroshi.com */
12
+ baseUrl?: string;
13
+ /** Retries after the first try for requests that are safe to repeat (default 2). */
14
+ maxRetries?: number;
15
+ /** Time for one try until the answer's headers arrive, in ms (default 60 000). */
16
+ timeoutMs?: number;
17
+ /** A fetch to use instead of the global one. */
18
+ fetch?: FetchFn;
19
+ }
20
+ /** A page of a numbered list: the rows and `meta` (page, per_page, total, has_next…). */
21
+ export interface Page<Row> {
22
+ data: Row[];
23
+ meta: T.Meta;
24
+ }
25
+ type BodyOf<D> = D extends {
26
+ body: infer B;
27
+ } ? B : never;
28
+ type QueryOf<D> = D extends {
29
+ query?: infer Q;
30
+ } ? NonNullable<Q> : never;
31
+ /** Write options: `idempotencyKey` makes a retry safe (one is made for you when you don't pass it). */
32
+ export interface WriteOptions {
33
+ idempotencyKey?: string;
34
+ }
35
+ /**
36
+ * Edit options: `ifMatch` is the row's `version`; the API answers 412 when someone changed it meanwhile. A response
37
+ * without a version (`null`) sends no precondition.
38
+ */
39
+ export interface EditOptions {
40
+ ifMatch?: string | number | null;
41
+ }
42
+ /**
43
+ * The Degroshi API client. Amounts are strings, as the API sends them ("642.30"): never parse them into numbers when
44
+ * you add them up.
45
+ *
46
+ * ```ts
47
+ * const degroshi = new Degroshi({ apiKey: process.env.DEGROSHI_API_KEY })
48
+ * for await (const transaction of degroshi.transactions.iterate({ from_date: "2026-11-01" })) { ... }
49
+ * ```
50
+ */
51
+ export declare class Degroshi {
52
+ /** The generated client underneath, for calling the generated functions directly (`client: degroshi.client`). */
53
+ readonly client: Client;
54
+ constructor(options?: DegroshiOptions);
55
+ /** The envelope of a successful call, or the error it failed with. */
56
+ private envelope;
57
+ private one;
58
+ private page;
59
+ private writeHeaders;
60
+ private editHeaders;
61
+ /** The spaces the token reaches. */
62
+ readonly spaces: {
63
+ list: () => Promise<T.MySpaceResponse[]>;
64
+ };
65
+ readonly accounts: {
66
+ list: (query?: QueryOf<T.ListAccountsData>) => Promise<T.AccountListResponse[]>;
67
+ get: (id: string) => Promise<T.AccountResponse>;
68
+ netWorth: (query?: QueryOf<T.GetAccountsNetWorthData>) => Promise<T.NetWorthResponse>;
69
+ };
70
+ readonly transactions: {
71
+ /** One page; `meta.has_next` says whether another follows. */
72
+ list: (query?: QueryOf<T.ListTransactionsData>) => Promise<Page<T.TransactionResponse>>;
73
+ /** Every matching transaction, page after page. */
74
+ iterate: (query?: QueryOf<T.ListTransactionsData>) => AsyncGenerator<T.TransactionResponse, any, any>;
75
+ get: (id: string) => Promise<T.TransactionResponse>;
76
+ create: (body: BodyOf<T.CreateTransactionData>, options?: WriteOptions) => Promise<T.TransactionResponse>;
77
+ update: (id: string, body: BodyOf<T.UpdateTransactionData>, options?: EditOptions) => Promise<T.TransactionResponse>;
78
+ delete: (id: string, options?: EditOptions) => Promise<undefined>;
79
+ dayTotals: (query?: QueryOf<T.GetTransactionDayTotalsData>) => Promise<T.DayTotalsResponse>;
80
+ };
81
+ readonly categories: {
82
+ list: (query?: QueryOf<T.ListCategoriesData>) => Promise<T.Category[]>;
83
+ get: (id: string) => Promise<T.Category>;
84
+ };
85
+ readonly budgets: {
86
+ list: (query?: QueryOf<T.ListBudgetsData>) => Promise<T.BudgetListItem[]>;
87
+ get: (id: string) => Promise<T.BudgetResponse>;
88
+ };
89
+ readonly recurring: {
90
+ list: (query?: QueryOf<T.ListRecurringTransactionsData>) => Promise<unknown>;
91
+ get: (id: string) => Promise<unknown>;
92
+ occurrences: (query?: QueryOf<T.ListRecurringOccurrencesData>) => Promise<T.OccurrencesResponse>;
93
+ };
94
+ readonly analytics: {
95
+ summary: (query: QueryOf<T.GetAnalyticsSummaryData>) => Promise<unknown>;
96
+ cashFlow: (query: QueryOf<T.GetAnalyticsCashFlowData>) => Promise<T.CashFlowResponse>;
97
+ categories: (query: QueryOf<T.GetAnalyticsCategoriesData>) => Promise<T.CategoryAnalyticsResponse>;
98
+ spending: (query: QueryOf<T.GetAnalyticsSpendingData>) => Promise<unknown>;
99
+ trends: (query: QueryOf<T.GetAnalyticsTrendsData>) => Promise<unknown>;
100
+ merchants: (query: QueryOf<T.GetAnalyticsMerchantsData>) => Promise<T.MerchantAnalyticsResponse>;
101
+ netWorth: (query: QueryOf<T.GetAnalyticsNetWorthData>) => Promise<T.NetWorthTimeSeriesResponse>;
102
+ };
103
+ /** Custom sources: push accounts, transactions and balances from your own system. */
104
+ readonly sources: {
105
+ list: () => Promise<unknown>;
106
+ get: (id: string) => Promise<unknown>;
107
+ create: (body: BodyOf<T.CreateSourceData>, options?: WriteOptions) => Promise<unknown>;
108
+ update: (id: string, body: BodyOf<T.UpdateSourceData>) => Promise<unknown>;
109
+ delete: (id: string) => Promise<undefined>;
110
+ upsertAccount: (id: string, externalId: string, body: BodyOf<T.UpsertSourceAccountData>) => Promise<unknown>;
111
+ /** Up to 500 rows; safe to retry (an Idempotency-Key is sent for you). */
112
+ pushTransactions: (id: string, body: BodyOf<T.PushSourceTransactionsData>, options?: WriteOptions) => Promise<T.PushBatchResponse>;
113
+ pushBalances: (id: string, body: BodyOf<T.PushSourceBalancesData>, options?: WriteOptions) => Promise<T.BalanceBatchResponse>;
114
+ /** What the space holds from the source, newest first, one page. */
115
+ listPushed: (id: string, query: QueryOf<T.ListSourceTransactionsData>) => Promise<T.PushedPage>;
116
+ /** Every row the space holds from the source, following next_cursor. */
117
+ iteratePushed: (id: string, query: QueryOf<T.ListSourceTransactionsData>) => AsyncGenerator<T.PushedRow, any, any>;
118
+ deletePushed: (id: string, account: string, externalId: string) => Promise<undefined>;
119
+ };
120
+ /** The space's events of the last 30 days, as webhook endpoints receive them. */
121
+ readonly events: {
122
+ list: (query?: QueryOf<T.ListEventsData>) => Promise<{
123
+ data: WebhookEvent[];
124
+ meta: {
125
+ has_more: boolean;
126
+ };
127
+ }>;
128
+ iterate: (query?: QueryOf<T.ListEventsData>) => AsyncGenerator<WebhookEvent, any, any>;
129
+ get: (id: string) => Promise<WebhookEvent>;
130
+ };
131
+ /** Webhook signatures: `await degroshi.webhooks.verify(rawBody, request.headers.get("Degroshi-Signature"), secret)`. */
132
+ readonly webhooks: {
133
+ verify: (rawBody: string | Uint8Array | ArrayBuffer, header: string | null | undefined, secret: string, options?: VerifyOptions) => Promise<WebhookEvent>;
134
+ };
135
+ private iterateTransactions;
136
+ private eventPage;
137
+ private iterateEvents;
138
+ private iteratePushedRows;
139
+ }
140
+ export { DegroshiError };
package/dist/client.js ADDED
@@ -0,0 +1,171 @@
1
+ import { createClient, createConfig } from "./generated/client/index.js";
2
+ import * as api from "./generated/sdk.gen.js";
3
+ import { ApiConnectionError, DegroshiError, errorBodyOf, errorFor } from "./errors.js";
4
+ import { retryingFetch } from "./retry.js";
5
+ import { SDK_VERSION } from "./version.js";
6
+ import { verifyWebhook } from "./webhooks.js";
7
+ function readEnv(name) {
8
+ const env = globalThis.process?.env;
9
+ return env?.[name];
10
+ }
11
+ /**
12
+ * The Degroshi API client. Amounts are strings, as the API sends them ("642.30"): never parse them into numbers when
13
+ * you add them up.
14
+ *
15
+ * ```ts
16
+ * const degroshi = new Degroshi({ apiKey: process.env.DEGROSHI_API_KEY })
17
+ * for await (const transaction of degroshi.transactions.iterate({ from_date: "2026-11-01" })) { ... }
18
+ * ```
19
+ */
20
+ export class Degroshi {
21
+ /** The generated client underneath, for calling the generated functions directly (`client: degroshi.client`). */
22
+ client;
23
+ constructor(options = {}) {
24
+ const apiKey = options.apiKey ?? readEnv("DEGROSHI_API_KEY");
25
+ if (!apiKey)
26
+ throw new Error("degroshi: pass apiKey or set DEGROSHI_API_KEY");
27
+ const headers = { "X-Degroshi-SDK": `js/${SDK_VERSION}` };
28
+ if (options.spaceId)
29
+ headers["X-Space-ID"] = options.spaceId;
30
+ this.client = createClient(createConfig({
31
+ baseUrl: options.baseUrl ?? "https://api.degroshi.com",
32
+ auth: apiKey,
33
+ headers,
34
+ fetch: retryingFetch(options.fetch ?? globalThis.fetch.bind(globalThis), {
35
+ maxRetries: options.maxRetries ?? 2,
36
+ timeoutMs: options.timeoutMs ?? 60_000,
37
+ }),
38
+ }));
39
+ }
40
+ /** The envelope of a successful call, or the error it failed with. */
41
+ async envelope(call) {
42
+ const result = await call;
43
+ const response = result.response;
44
+ if (response?.ok)
45
+ return (result.data ?? {});
46
+ if (!response) {
47
+ throw result.error instanceof Error ? result.error : new ApiConnectionError(result.error);
48
+ }
49
+ throw errorFor(response.status, errorBodyOf(response.status, result.error), response.headers);
50
+ }
51
+ async one(call) {
52
+ return (await this.envelope(call)).data;
53
+ }
54
+ async page(call) {
55
+ const envelope = await this.envelope(call);
56
+ return { data: (envelope.data ?? []), meta: envelope.meta };
57
+ }
58
+ writeHeaders(options = {}) {
59
+ return { "Idempotency-Key": options.idempotencyKey ?? crypto.randomUUID() };
60
+ }
61
+ editHeaders(options = {}) {
62
+ return options.ifMatch == null ? {} : { "If-Match": String(options.ifMatch) };
63
+ }
64
+ /** The spaces the token reaches. */
65
+ spaces = {
66
+ list: () => this.one(api.listMySpaces({ client: this.client })),
67
+ };
68
+ accounts = {
69
+ list: (query) => this.one(api.listAccounts({ client: this.client, query })),
70
+ get: (id) => this.one(api.getAccount({ client: this.client, path: { id } })),
71
+ netWorth: (query) => this.one(api.getAccountsNetWorth({ client: this.client, query })),
72
+ };
73
+ transactions = {
74
+ /** One page; `meta.has_next` says whether another follows. */
75
+ list: (query) => this.page(api.listTransactions({ client: this.client, query })),
76
+ /** Every matching transaction, page after page. */
77
+ iterate: (query = {}) => this.iterateTransactions(query),
78
+ get: (id) => this.one(api.getTransaction({ client: this.client, path: { id } })),
79
+ create: (body, options) => this.one(api.createTransaction({ client: this.client, body, headers: this.writeHeaders(options) })),
80
+ update: (id, body, options) => this.one(api.updateTransaction({ client: this.client, path: { id }, body, headers: this.editHeaders(options) })),
81
+ delete: (id, options) => this.envelope(api.deleteTransaction({ client: this.client, path: { id }, headers: this.editHeaders(options) })).then(() => undefined),
82
+ dayTotals: (query) => this.one(api.getTransactionDayTotals({ client: this.client, query })),
83
+ };
84
+ categories = {
85
+ list: (query) => this.one(api.listCategories({ client: this.client, query })),
86
+ get: (id) => this.one(api.getCategory({ client: this.client, path: { id } })),
87
+ };
88
+ budgets = {
89
+ list: (query) => this.one(api.listBudgets({ client: this.client, query })),
90
+ get: (id) => this.one(api.getBudget({ client: this.client, path: { id } })),
91
+ };
92
+ recurring = {
93
+ list: (query) => this.one(api.listRecurringTransactions({ client: this.client, query })),
94
+ get: (id) => this.one(api.getRecurringTransaction({ client: this.client, path: { id } })),
95
+ occurrences: (query) => this.one(api.listRecurringOccurrences({ client: this.client, query })),
96
+ };
97
+ analytics = {
98
+ summary: (query) => this.one(api.getAnalyticsSummary({ client: this.client, query })),
99
+ cashFlow: (query) => this.one(api.getAnalyticsCashFlow({ client: this.client, query })),
100
+ categories: (query) => this.one(api.getAnalyticsCategories({ client: this.client, query })),
101
+ spending: (query) => this.one(api.getAnalyticsSpending({ client: this.client, query })),
102
+ trends: (query) => this.one(api.getAnalyticsTrends({ client: this.client, query })),
103
+ merchants: (query) => this.one(api.getAnalyticsMerchants({ client: this.client, query })),
104
+ netWorth: (query) => this.one(api.getAnalyticsNetWorth({ client: this.client, query })),
105
+ };
106
+ /** Custom sources: push accounts, transactions and balances from your own system. */
107
+ sources = {
108
+ list: () => this.one(api.listSources({ client: this.client })),
109
+ get: (id) => this.one(api.getSource({ client: this.client, path: { id } })),
110
+ create: (body, options) => this.one(api.createSource({ client: this.client, body, headers: this.writeHeaders(options) })),
111
+ update: (id, body) => this.one(api.updateSource({ client: this.client, path: { id }, body })),
112
+ delete: (id) => this.envelope(api.deleteSource({ client: this.client, path: { id } })).then(() => undefined),
113
+ upsertAccount: (id, externalId, body) => this.one(api.upsertSourceAccount({ client: this.client, path: { id, external_id: externalId }, body })),
114
+ /** Up to 500 rows; safe to retry (an Idempotency-Key is sent for you). */
115
+ pushTransactions: (id, body, options) => this.one(api.pushSourceTransactions({ client: this.client, path: { id }, body, headers: this.writeHeaders(options) })),
116
+ pushBalances: (id, body, options) => this.one(api.pushSourceBalances({ client: this.client, path: { id }, body, headers: this.writeHeaders(options) })),
117
+ /** What the space holds from the source, newest first, one page. */
118
+ listPushed: (id, query) => this.one(api.listSourceTransactions({ client: this.client, path: { id }, query })),
119
+ /** Every row the space holds from the source, following next_cursor. */
120
+ iteratePushed: (id, query) => this.iteratePushedRows(id, query),
121
+ deletePushed: (id, account, externalId) => this.envelope(api.deleteSourceTransaction({ client: this.client, path: { id, account, external_id: externalId } })).then(() => undefined),
122
+ };
123
+ /** The space's events of the last 30 days, as webhook endpoints receive them. */
124
+ events = {
125
+ list: (query) => this.eventPage(query),
126
+ iterate: (query = {}) => this.iterateEvents(query),
127
+ get: (id) => this.one(api.getEvent({ client: this.client, path: { id } })),
128
+ };
129
+ /** Webhook signatures: `await degroshi.webhooks.verify(rawBody, request.headers.get("Degroshi-Signature"), secret)`. */
130
+ webhooks = {
131
+ verify: (rawBody, header, secret, options) => verifyWebhook(rawBody, header, secret, options),
132
+ };
133
+ async *iterateTransactions(query) {
134
+ for (let page = query.page ?? 1;; page++) {
135
+ const result = await this.transactions.list({ ...query, page, per_page: query.per_page ?? 100 });
136
+ yield* result.data;
137
+ if (!result.meta?.has_next || result.data.length === 0)
138
+ return;
139
+ }
140
+ }
141
+ async eventPage(query) {
142
+ const envelope = await this.envelope(api.listEvents({ client: this.client, query }));
143
+ return {
144
+ data: (envelope.data ?? []),
145
+ meta: { has_more: Boolean(envelope.meta?.has_more) },
146
+ };
147
+ }
148
+ async *iterateEvents(query) {
149
+ let cursor = query.starting_after;
150
+ for (;;) {
151
+ const result = await this.eventPage({ ...query, starting_after: cursor });
152
+ yield* result.data;
153
+ const last = result.data.at(-1);
154
+ if (!result.meta.has_more || !last)
155
+ return;
156
+ cursor = last.id;
157
+ }
158
+ }
159
+ async *iteratePushedRows(id, query) {
160
+ let cursor = query.cursor;
161
+ for (;;) {
162
+ const page = await this.sources.listPushed(id, { ...query, cursor });
163
+ yield* page.items ?? [];
164
+ if (!page.next_cursor)
165
+ return;
166
+ cursor = page.next_cursor;
167
+ }
168
+ }
169
+ }
170
+ export { DegroshiError };
171
+ //# sourceMappingURL=client.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,56 @@
1
+ /** What the API sends with an error: `{ success: false, error: { code, message, details, correlation_id } }`. */
2
+ export interface ApiErrorBody {
3
+ code: string;
4
+ message: string;
5
+ details?: Record<string, unknown>;
6
+ correlation_id?: string;
7
+ }
8
+ /** Any error the API answered with. `code` is the API's error code, e.g. `TXN_ACCOUNT_CONNECTED`. */
9
+ export declare class DegroshiError extends Error {
10
+ readonly status: number;
11
+ readonly code: string;
12
+ readonly details: Record<string, unknown>;
13
+ /** Include it when you report a problem: it finds the request in our logs. */
14
+ readonly correlationId: string | undefined;
15
+ readonly headers: Headers | undefined;
16
+ constructor(status: number, body: ApiErrorBody, headers?: Headers);
17
+ }
18
+ /** 400 or 422: the request is malformed or breaks a rule. */
19
+ export declare class BadRequestError extends DegroshiError {
20
+ }
21
+ /** 401: the key is missing, wrong, expired or revoked. */
22
+ export declare class AuthenticationError extends DegroshiError {
23
+ }
24
+ /** 403: the key lacks the scope, the space or the role for this. */
25
+ export declare class PermissionDeniedError extends DegroshiError {
26
+ }
27
+ /** 404: no such resource in the space. */
28
+ export declare class NotFoundError extends DegroshiError {
29
+ }
30
+ /** 409 or 412: it changed meanwhile, or the version you sent is old. */
31
+ export declare class ConflictError extends DegroshiError {
32
+ }
33
+ /** 422: understood but refused, e.g. a bank-kept account takes no rows. */
34
+ export declare class UnprocessableEntityError extends DegroshiError {
35
+ }
36
+ /** 429: too many requests. `retryAfterSeconds` says when to try again. */
37
+ export declare class RateLimitError extends DegroshiError {
38
+ get retryAfterSeconds(): number | undefined;
39
+ }
40
+ /** 5xx: our side failed. Retried for you when it's safe; this is the last answer. */
41
+ export declare class InternalServerError extends DegroshiError {
42
+ }
43
+ /** The request never got an answer: no connection, or the connection broke. */
44
+ export declare class ApiConnectionError extends Error {
45
+ constructor(cause: unknown);
46
+ }
47
+ /** No answer within the client's timeout. */
48
+ export declare class ApiTimeoutError extends ApiConnectionError {
49
+ constructor(cause: unknown);
50
+ }
51
+ /** The error class for an HTTP status. */
52
+ export declare function errorFor(status: number, body: ApiErrorBody, headers?: Headers): DegroshiError;
53
+ /** Reads an error answer into its body; a non-JSON answer keeps its text as the message. */
54
+ export declare function errorBodyOf(status: number, parsed: unknown): ApiErrorBody;
55
+ /** Seconds from a Retry-After header: a number of seconds or an HTTP date. */
56
+ export declare function parseRetryAfter(value: string | null, now?: number): number | undefined;