@theholocron/holocron-plugin-cloudflare 5.0.0-alpha.278 → 5.0.0-alpha.279
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/dist/index.d.mts +29 -0
- package/dist/index.mjs +25 -0
- package/package.json +6 -6
package/dist/index.d.mts
CHANGED
|
@@ -1,14 +1,19 @@
|
|
|
1
1
|
import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, WikiProxyConfig, WorkerScriptState, Workers } from "@theholocron/cli";
|
|
2
2
|
import { CloudflareClient, CloudflareClient as CloudflareClient$1, CloudflareClientOptions, createCloudflareClient } from "@theholocron/cloudflare-client";
|
|
3
|
+
/** Resolves the Cloudflare API token from `--token`, `HOLOCRON_CLOUDFLARE_TOKEN`, `CLOUDFLARE_API_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
|
|
3
4
|
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
4
5
|
/** Every token this plugin takes, for `holocron doctor tokens`. */
|
|
5
6
|
export declare const tokens: PluginToken[];
|
|
7
|
+
/** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
|
|
6
8
|
export declare class CloudflareDeployment implements Deployment {
|
|
7
9
|
private readonly client;
|
|
8
10
|
private readonly accountId;
|
|
11
|
+
/** The capability this class provides, always `"deployment"`. */
|
|
9
12
|
readonly key: "deployment";
|
|
13
|
+
/** The provider name, `"cloudflare"`. */
|
|
10
14
|
readonly providerName = "cloudflare";
|
|
11
15
|
constructor(client: () => CloudflareClient, accountId: string);
|
|
16
|
+
/** Lists the account's Pages projects. */
|
|
12
17
|
listProjects(): Promise<DeploymentProject[]>;
|
|
13
18
|
ensureProject(input: {
|
|
14
19
|
name: string;
|
|
@@ -16,28 +21,38 @@ export declare class CloudflareDeployment implements Deployment {
|
|
|
16
21
|
repo?: string;
|
|
17
22
|
rootDirectory?: string;
|
|
18
23
|
}): Promise<DeploymentProject>;
|
|
24
|
+
/** Returns the project as it is now; Pages has no REST setting for the requested options, so `settings` is ignored. */
|
|
19
25
|
updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
|
|
26
|
+
/** Lists the names of the environment variables set for the production or preview target. */
|
|
20
27
|
listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
|
|
28
|
+
/** Sets a plain-text environment variable on the production or preview target, keeping the others. */
|
|
21
29
|
setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
|
|
22
30
|
triggerDeployment(input: {
|
|
23
31
|
projectId: string;
|
|
24
32
|
branch: string;
|
|
25
33
|
target?: DeploymentTrigger;
|
|
26
34
|
}): Promise<DeploymentRecord>;
|
|
35
|
+
/** Fetches a deployment by an id of the form `projectName:deploymentId`; throws a 400 `ProviderApiError` for any other form. */
|
|
27
36
|
getDeployment(deploymentId: string): Promise<DeploymentRecord>;
|
|
28
37
|
listPreviewDeployments(projectId: string, branch: string): Promise<DeploymentRecord[]>;
|
|
29
38
|
deletePreviewDeployments(projectId: string, deploymentIds: string[]): Promise<number>;
|
|
30
39
|
ensureCustomDomain(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
|
|
31
40
|
private getProjectByName;
|
|
32
41
|
}
|
|
42
|
+
/** The Cloudflare implementation of the `dns` capability; finds a domain's zone by walking from the domain up to its apex. */
|
|
33
43
|
export declare class CloudflareDns implements Dns {
|
|
34
44
|
private readonly client;
|
|
45
|
+
/** The capability this class provides, always `"dns"`. */
|
|
35
46
|
readonly key: "dns";
|
|
47
|
+
/** The provider name, `"cloudflare"`. */
|
|
36
48
|
readonly providerName = "cloudflare";
|
|
37
49
|
private readonly zoneCache;
|
|
38
50
|
constructor(client: () => CloudflareClient);
|
|
51
|
+
/** Lists the DNS records in the zone that holds the domain. */
|
|
39
52
|
listRecords(domain: string): Promise<DnsRecord[]>;
|
|
53
|
+
/** Updates the first record of the same type and name, or creates the record when there is none; returns the stored record. */
|
|
40
54
|
upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
|
|
55
|
+
/** Deletes the DNS record with this id from the zone that holds the domain. */
|
|
41
56
|
deleteRecord(domain: string, id: string): Promise<void>;
|
|
42
57
|
/** `holocron doctor` has no specific domain to check — lists every zone the token can see instead. */
|
|
43
58
|
whoami(): Promise<{
|
|
@@ -53,10 +68,13 @@ export declare class CloudflareDns implements Dns {
|
|
|
53
68
|
*/
|
|
54
69
|
private resolveZone;
|
|
55
70
|
}
|
|
71
|
+
/** The Cloudflare implementation of the `workers` capability, backed by Workers scripts and routes in one account. */
|
|
56
72
|
export declare class CloudflareWorkers implements Workers {
|
|
57
73
|
private readonly client;
|
|
58
74
|
private readonly accountId;
|
|
75
|
+
/** The capability this class provides, always `"workers"`. */
|
|
59
76
|
readonly key: "workers";
|
|
77
|
+
/** The provider name, `"cloudflare"`. */
|
|
60
78
|
readonly providerName = "cloudflare";
|
|
61
79
|
private readonly zoneCache;
|
|
62
80
|
constructor(client: () => Pick<CloudflareClient$1, "workers" | "zones">, accountId: string);
|
|
@@ -82,7 +100,9 @@ interface VerifyTokenOptions {
|
|
|
82
100
|
baseUrl?: string;
|
|
83
101
|
fetch?: typeof fetch;
|
|
84
102
|
}
|
|
103
|
+
/** Checks a Cloudflare API token, first by the token-verify endpoint and otherwise by listing zones; resolves to a description of what it found, or the failure message. */
|
|
85
104
|
export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
|
|
105
|
+
/** Options for the Cloudflare plugin: how the API token is resolved, the account, and test overrides. */
|
|
86
106
|
export interface CloudflarePluginOptions extends ResolveTokenInput {
|
|
87
107
|
/**
|
|
88
108
|
* Cloudflare account ID. Required for Pages (deployment) operations;
|
|
@@ -91,19 +111,27 @@ export interface CloudflarePluginOptions extends ResolveTokenInput {
|
|
|
91
111
|
accountId?: string;
|
|
92
112
|
/** Override base URL for tests. */
|
|
93
113
|
baseUrl?: string;
|
|
114
|
+
/** The `fetch` to use instead of the global one, for tests. */
|
|
94
115
|
fetch?: typeof fetch;
|
|
95
116
|
}
|
|
117
|
+
/** The shared state the Cloudflare plugin's capabilities and probes are built from. */
|
|
96
118
|
export interface PluginContext {
|
|
119
|
+
/** The options the plugin was created with, with `accountId` falling back to `CLOUDFLARE_ACCOUNT_ID`. */
|
|
97
120
|
options: CloudflarePluginOptions;
|
|
98
121
|
/** Memoized client — the token is resolved on first use, not at plugin load. */
|
|
99
122
|
client: () => CloudflareClient;
|
|
100
123
|
/** Memoized token resolver — shared by the client and the Workers capability. */
|
|
101
124
|
token: () => string;
|
|
102
125
|
}
|
|
126
|
+
/** Builds the plugin context from its options; the API token is resolved lazily on the first client use. */
|
|
103
127
|
export declare function createContext(options?: CloudflarePluginOptions): PluginContext;
|
|
128
|
+
/** Builds the `dns` capability for a context. */
|
|
104
129
|
export declare function dns(ctx: PluginContext): Dns;
|
|
130
|
+
/** Builds the `deployment` capability for a context; throws when no account id is set. */
|
|
105
131
|
export declare function deployment(ctx: PluginContext): Deployment;
|
|
132
|
+
/** Builds the `workers` capability for a context; throws when no account id is set. */
|
|
106
133
|
export declare function workersCapability(ctx: PluginContext): Workers;
|
|
134
|
+
/** Creates the Cloudflare plugin: `dns` always, plus `deployment` and `workers` when an account id is set, and a `connection` probe. */
|
|
107
135
|
export declare function createPlugin(options?: CloudflarePluginOptions): {
|
|
108
136
|
name: string;
|
|
109
137
|
probes: {
|
|
@@ -115,5 +143,6 @@ export declare function createPlugin(options?: CloudflarePluginOptions): {
|
|
|
115
143
|
dns: () => Dns;
|
|
116
144
|
};
|
|
117
145
|
};
|
|
146
|
+
/** One-line hint printed by `holocron auth set cloudflare` when no token is supplied or the supplied one is rejected. */
|
|
118
147
|
export declare const AUTH_HINT: string;
|
|
119
148
|
export { AuthError, type CloudflareClient, type CloudflareClientOptions, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createCloudflareClient };
|
package/dist/index.mjs
CHANGED
|
@@ -2,6 +2,7 @@ import { AuthError, ProviderApiError, connectionProbe, createResolveToken } from
|
|
|
2
2
|
import { createCloudflareClient } from "@theholocron/cloudflare-client";
|
|
3
3
|
import { errorMessage } from "@theholocron/misc-utils";
|
|
4
4
|
// src/auth.ts
|
|
5
|
+
/** Resolves the Cloudflare API token from `--token`, `HOLOCRON_CLOUDFLARE_TOKEN`, `CLOUDFLARE_API_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
|
|
5
6
|
const resolveToken = createResolveToken({
|
|
6
7
|
envName: "HOLOCRON_CLOUDFLARE_TOKEN",
|
|
7
8
|
vendorEnvName: "CLOUDFLARE_API_TOKEN",
|
|
@@ -11,15 +12,19 @@ const resolveToken = createResolveToken({
|
|
|
11
12
|
/** Every token this plugin takes, for `holocron doctor tokens`. */
|
|
12
13
|
const tokens = [resolveToken.token];
|
|
13
14
|
// src/capabilities/deployment.ts
|
|
15
|
+
/** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
|
|
14
16
|
var CloudflareDeployment = class {
|
|
15
17
|
client;
|
|
16
18
|
accountId;
|
|
19
|
+
/** The capability this class provides, always `"deployment"`. */
|
|
17
20
|
key = "deployment";
|
|
21
|
+
/** The provider name, `"cloudflare"`. */
|
|
18
22
|
providerName = "cloudflare";
|
|
19
23
|
constructor(client, accountId) {
|
|
20
24
|
this.client = client;
|
|
21
25
|
this.accountId = accountId;
|
|
22
26
|
}
|
|
27
|
+
/** Lists the account's Pages projects. */
|
|
23
28
|
async listProjects() {
|
|
24
29
|
return (await this.client().pages.listProjects(this.accountId)).map(mapProject);
|
|
25
30
|
}
|
|
@@ -31,14 +36,17 @@ var CloudflareDeployment = class {
|
|
|
31
36
|
production_branch: "main"
|
|
32
37
|
}));
|
|
33
38
|
}
|
|
39
|
+
/** Returns the project as it is now; Pages has no REST setting for the requested options, so `settings` is ignored. */
|
|
34
40
|
async updateProjectSettings(projectId, settings) {
|
|
35
41
|
return mapProject(await this.client().pages.getProject(this.accountId, projectId));
|
|
36
42
|
}
|
|
43
|
+
/** Lists the names of the environment variables set for the production or preview target. */
|
|
37
44
|
async listEnvVars(projectId, target) {
|
|
38
45
|
const project = await this.client().pages.getProject(this.accountId, projectId);
|
|
39
46
|
const envConfig = target === "production" ? project.deployment_configs.production : project.deployment_configs.preview;
|
|
40
47
|
return Object.keys(envConfig.env_vars);
|
|
41
48
|
}
|
|
49
|
+
/** Sets a plain-text environment variable on the production or preview target, keeping the others. */
|
|
42
50
|
async setEnvVar(projectId, target, name, value) {
|
|
43
51
|
const cfg = (await this.client().pages.getProject(this.accountId, projectId)).deployment_configs;
|
|
44
52
|
const scope = target === "production" ? "production" : "preview";
|
|
@@ -57,6 +65,7 @@ var CloudflareDeployment = class {
|
|
|
57
65
|
async triggerDeployment(input) {
|
|
58
66
|
return mapDeployment(await this.client().pages.createDeployment(this.accountId, input.projectId, input.branch), input.projectId, input.branch, input.target);
|
|
59
67
|
}
|
|
68
|
+
/** Fetches a deployment by an id of the form `projectName:deploymentId`; throws a 400 `ProviderApiError` for any other form. */
|
|
60
69
|
async getDeployment(deploymentId) {
|
|
61
70
|
const sep = deploymentId.indexOf(":");
|
|
62
71
|
if (sep === -1) throw new ProviderApiError(`Invalid Cloudflare Pages deployment id "${deploymentId}" — expected "projectName:deploymentId"`, 400, void 0);
|
|
@@ -117,18 +126,23 @@ function normalizeStatus(status) {
|
|
|
117
126
|
}
|
|
118
127
|
}
|
|
119
128
|
// src/capabilities/dns.ts
|
|
129
|
+
/** The Cloudflare implementation of the `dns` capability; finds a domain's zone by walking from the domain up to its apex. */
|
|
120
130
|
var CloudflareDns = class {
|
|
121
131
|
client;
|
|
132
|
+
/** The capability this class provides, always `"dns"`. */
|
|
122
133
|
key = "dns";
|
|
134
|
+
/** The provider name, `"cloudflare"`. */
|
|
123
135
|
providerName = "cloudflare";
|
|
124
136
|
zoneCache = /* @__PURE__ */ new Map();
|
|
125
137
|
constructor(client) {
|
|
126
138
|
this.client = client;
|
|
127
139
|
}
|
|
140
|
+
/** Lists the DNS records in the zone that holds the domain. */
|
|
128
141
|
async listRecords(domain) {
|
|
129
142
|
const zoneId = await this.resolveZone(domain);
|
|
130
143
|
return (await this.client().dns.list(zoneId)).map(mapRecord);
|
|
131
144
|
}
|
|
145
|
+
/** Updates the first record of the same type and name, or creates the record when there is none; returns the stored record. */
|
|
132
146
|
async upsertRecord(domain, record) {
|
|
133
147
|
const client = this.client();
|
|
134
148
|
const zoneId = await this.resolveZone(domain);
|
|
@@ -151,6 +165,7 @@ var CloudflareDns = class {
|
|
|
151
165
|
...record.proxied !== void 0 ? { proxied: record.proxied } : {}
|
|
152
166
|
}));
|
|
153
167
|
}
|
|
168
|
+
/** Deletes the DNS record with this id from the zone that holds the domain. */
|
|
154
169
|
async deleteRecord(domain, id) {
|
|
155
170
|
const zoneId = await this.resolveZone(domain);
|
|
156
171
|
await this.client().dns.delete(zoneId, id);
|
|
@@ -195,10 +210,13 @@ function mapRecord(raw) {
|
|
|
195
210
|
};
|
|
196
211
|
}
|
|
197
212
|
// src/capabilities/workers.ts
|
|
213
|
+
/** The Cloudflare implementation of the `workers` capability, backed by Workers scripts and routes in one account. */
|
|
198
214
|
var CloudflareWorkers = class {
|
|
199
215
|
client;
|
|
200
216
|
accountId;
|
|
217
|
+
/** The capability this class provides, always `"workers"`. */
|
|
201
218
|
key = "workers";
|
|
219
|
+
/** The provider name, `"cloudflare"`. */
|
|
202
220
|
providerName = "cloudflare";
|
|
203
221
|
zoneCache = /* @__PURE__ */ new Map();
|
|
204
222
|
constructor(client, accountId) {
|
|
@@ -293,6 +311,7 @@ function generateProxyScript(config) {
|
|
|
293
311
|
].join("\n");
|
|
294
312
|
}
|
|
295
313
|
// src/verify-token.ts
|
|
314
|
+
/** Checks a Cloudflare API token, first by the token-verify endpoint and otherwise by listing zones; resolves to a description of what it found, or the failure message. */
|
|
296
315
|
async function verifyToken(token, opts = {}) {
|
|
297
316
|
const client = createCloudflareClient({
|
|
298
317
|
token,
|
|
@@ -324,6 +343,7 @@ async function verifyToken(token, opts = {}) {
|
|
|
324
343
|
}
|
|
325
344
|
}
|
|
326
345
|
// src/index.ts
|
|
346
|
+
/** Builds the plugin context from its options; the API token is resolved lazily on the first client use. */
|
|
327
347
|
function createContext(options = {}) {
|
|
328
348
|
const accountId = options.accountId ?? process.env.CLOUDFLARE_ACCOUNT_ID;
|
|
329
349
|
const opts = {
|
|
@@ -343,17 +363,21 @@ function createContext(options = {}) {
|
|
|
343
363
|
})
|
|
344
364
|
};
|
|
345
365
|
}
|
|
366
|
+
/** Builds the `dns` capability for a context. */
|
|
346
367
|
function dns(ctx) {
|
|
347
368
|
return new CloudflareDns(ctx.client);
|
|
348
369
|
}
|
|
370
|
+
/** Builds the `deployment` capability for a context; throws when no account id is set. */
|
|
349
371
|
function deployment(ctx) {
|
|
350
372
|
if (!ctx.options.accountId) throw new Error("Cloudflare accountId is required for Pages deployments — set accountId in the plugin options or CLOUDFLARE_ACCOUNT_ID env var");
|
|
351
373
|
return new CloudflareDeployment(ctx.client, ctx.options.accountId);
|
|
352
374
|
}
|
|
375
|
+
/** Builds the `workers` capability for a context; throws when no account id is set. */
|
|
353
376
|
function workersCapability(ctx) {
|
|
354
377
|
if (!ctx.options.accountId) throw new Error("Cloudflare accountId is required for Workers — set accountId in the plugin options or CLOUDFLARE_ACCOUNT_ID env var");
|
|
355
378
|
return new CloudflareWorkers(ctx.client, ctx.options.accountId);
|
|
356
379
|
}
|
|
380
|
+
/** Creates the Cloudflare plugin: `dns` always, plus `deployment` and `workers` when an account id is set, and a `connection` probe. */
|
|
357
381
|
function createPlugin(options = {}) {
|
|
358
382
|
const ctx = createContext(options);
|
|
359
383
|
return {
|
|
@@ -377,5 +401,6 @@ function createPlugin(options = {}) {
|
|
|
377
401
|
}
|
|
378
402
|
};
|
|
379
403
|
}
|
|
404
|
+
/** One-line hint printed by `holocron auth set cloudflare` when no token is supplied or the supplied one is rejected. */
|
|
380
405
|
const AUTH_HINT = "create an API token at https://dash.cloudflare.com/profile/api-tokens with Zone:Read, DNS:Edit, Cloudflare Pages:Edit, Workers Scripts:Edit (account-level), and Workers Routes:Edit (zone-level) permissions, then run: holocron auth set cloudflare <TOKEN>";
|
|
381
406
|
export { AUTH_HINT, AuthError, CloudflareDeployment, CloudflareDns, CloudflareWorkers, createCloudflareClient, createContext, createPlugin, deployment, dns, resolveToken, tokens, verifyToken, workersCapability };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/holocron-plugin-cloudflare",
|
|
3
|
-
"version": "5.0.0-alpha.
|
|
3
|
+
"version": "5.0.0-alpha.279",
|
|
4
4
|
"description": "Holocron plugin for Cloudflare. Implements the dns capability against Cloudflare's REST API — zone resolution, DNS record management.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cloudflare",
|
|
@@ -41,19 +41,19 @@
|
|
|
41
41
|
"tsx": "4.23.15",
|
|
42
42
|
"typescript": "^5.9.3",
|
|
43
43
|
"vitest": "^5.0.5",
|
|
44
|
-
"@theholocron/cli": "5.0.0-alpha.278",
|
|
45
|
-
"@theholocron/eslint-config": "^8.9.0-alpha.4",
|
|
46
44
|
"@theholocron/cloudflare-client": "^1.58.0-alpha.3",
|
|
47
45
|
"@theholocron/http-client": "^1.58.0-alpha.3",
|
|
48
|
-
"@theholocron/tsconfig": "^8.9.0-alpha.4",
|
|
49
46
|
"@theholocron/misc-utils": "^1.16.1-alpha.3",
|
|
47
|
+
"@theholocron/tsconfig": "^8.9.0-alpha.4",
|
|
48
|
+
"@theholocron/vitest-config": "^8.9.0-alpha.4",
|
|
50
49
|
"@theholocron/tsdown-config": "^8.9.0-alpha.4",
|
|
51
|
-
"@theholocron/
|
|
50
|
+
"@theholocron/cli": "5.0.0-alpha.279",
|
|
51
|
+
"@theholocron/eslint-config": "^8.9.0-alpha.4"
|
|
52
52
|
},
|
|
53
53
|
"peerDependencies": {
|
|
54
54
|
"@theholocron/cloudflare-client": "^1.53.1",
|
|
55
55
|
"@theholocron/misc-utils": "^1.16.0",
|
|
56
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
56
|
+
"@theholocron/cli": "5.0.0-alpha.279"
|
|
57
57
|
},
|
|
58
58
|
"peerDependenciesMeta": {
|
|
59
59
|
"@theholocron/cloudflare-client": {}
|