@start9labs/start-sdk 0.4.0-beta.51 → 0.4.0-beta.52

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 (146) hide show
  1. package/base/lib/actions/input/builder/inputSpec.d.ts +126 -5
  2. package/base/lib/actions/input/builder/inputSpec.js +219 -9
  3. package/base/lib/actions/input/builder/inputSpec.js.map +1 -1
  4. package/base/lib/actions/input/builder/list.d.ts +21 -0
  5. package/base/lib/actions/input/builder/list.js +21 -0
  6. package/base/lib/actions/input/builder/list.js.map +1 -1
  7. package/base/lib/actions/input/builder/value.d.ts +54 -0
  8. package/base/lib/actions/input/builder/value.js +56 -1
  9. package/base/lib/actions/input/builder/value.js.map +1 -1
  10. package/base/lib/actions/input/builder/variants.d.ts +11 -0
  11. package/base/lib/actions/input/builder/variants.js +17 -2
  12. package/base/lib/actions/input/builder/variants.js.map +1 -1
  13. package/base/lib/actions/input/inputSpecConstants.d.ts +203 -5
  14. package/base/lib/actions/input/inputSpecConstants.js +118 -38
  15. package/base/lib/actions/input/inputSpecConstants.js.map +1 -1
  16. package/base/lib/actions/input/inputSpecTypes.d.ts +99 -0
  17. package/base/lib/actions/input/inputSpecTypes.js +6 -1
  18. package/base/lib/actions/input/inputSpecTypes.js.map +1 -1
  19. package/base/lib/actions/setupActions.d.ts +6 -3
  20. package/base/lib/actions/setupActions.js +6 -3
  21. package/base/lib/actions/setupActions.js.map +1 -1
  22. package/base/lib/exver/index.d.ts +233 -2
  23. package/base/lib/exver/index.js +197 -3
  24. package/base/lib/exver/index.js.map +1 -1
  25. package/base/lib/index.d.ts +23 -1
  26. package/base/lib/index.js +3 -2
  27. package/base/lib/index.js.map +1 -1
  28. package/base/lib/inits/setupInit.d.ts +17 -0
  29. package/base/lib/inits/setupInit.js +7 -0
  30. package/base/lib/inits/setupInit.js.map +1 -1
  31. package/base/lib/inits/setupUninit.d.ts +12 -0
  32. package/base/lib/inits/setupUninit.js +7 -0
  33. package/base/lib/inits/setupUninit.js.map +1 -1
  34. package/base/lib/osBindings/ServerHostname.d.ts +1 -0
  35. package/base/lib/osBindings/ServerHostname.js +4 -0
  36. package/base/lib/osBindings/ServerHostname.js.map +1 -0
  37. package/base/lib/osBindings/ServerInfo.d.ts +1 -0
  38. package/base/lib/osBindings/SetServerHostnameParams.d.ts +4 -0
  39. package/base/lib/osBindings/SetServerHostnameParams.js +4 -0
  40. package/base/lib/osBindings/SetServerHostnameParams.js.map +1 -0
  41. package/base/lib/osBindings/SetupExecuteParams.d.ts +3 -1
  42. package/base/lib/osBindings/SmtpSecurity.d.ts +1 -0
  43. package/base/lib/osBindings/SmtpSecurity.js +4 -0
  44. package/base/lib/osBindings/SmtpSecurity.js.map +1 -0
  45. package/base/lib/osBindings/SmtpValue.d.ts +4 -2
  46. package/base/lib/osBindings/SmtpValue.js +0 -1
  47. package/base/lib/osBindings/SmtpValue.js.map +1 -1
  48. package/base/lib/osBindings/StartOsRecoveryInfo.d.ts +2 -2
  49. package/base/lib/osBindings/TestSmtpParams.d.ts +4 -2
  50. package/base/lib/osBindings/TestSmtpParams.js +0 -1
  51. package/base/lib/osBindings/TestSmtpParams.js.map +1 -1
  52. package/base/lib/osBindings/index.d.ts +3 -1
  53. package/base/lib/s9pk/index.d.ts +66 -0
  54. package/base/lib/s9pk/index.js +70 -1
  55. package/base/lib/s9pk/index.js.map +1 -1
  56. package/base/lib/types.d.ts +68 -2
  57. package/base/lib/types.js +14 -0
  58. package/base/lib/types.js.map +1 -1
  59. package/base/lib/util/asError.d.ts +8 -0
  60. package/base/lib/util/asError.js +8 -0
  61. package/base/lib/util/asError.js.map +1 -1
  62. package/base/lib/util/deepEqual.d.ts +15 -0
  63. package/base/lib/util/deepEqual.js +15 -0
  64. package/base/lib/util/deepEqual.js.map +1 -1
  65. package/base/lib/util/deepMerge.d.ts +18 -0
  66. package/base/lib/util/deepMerge.js +18 -0
  67. package/base/lib/util/deepMerge.js.map +1 -1
  68. package/base/lib/util/getDefaultString.d.ts +8 -0
  69. package/base/lib/util/getDefaultString.js +8 -0
  70. package/base/lib/util/getDefaultString.js.map +1 -1
  71. package/base/lib/util/graph.d.ts +57 -0
  72. package/base/lib/util/graph.js +47 -0
  73. package/base/lib/util/graph.js.map +1 -1
  74. package/base/lib/util/inMs.d.ts +15 -0
  75. package/base/lib/util/inMs.js +15 -0
  76. package/base/lib/util/inMs.js.map +1 -1
  77. package/base/lib/util/ip.d.ts +81 -0
  78. package/base/lib/util/ip.js +81 -0
  79. package/base/lib/util/ip.js.map +1 -1
  80. package/base/lib/util/once.d.ts +13 -0
  81. package/base/lib/util/once.js +13 -0
  82. package/base/lib/util/once.js.map +1 -1
  83. package/base/lib/util/patterns.d.ts +11 -0
  84. package/base/lib/util/patterns.js +11 -0
  85. package/base/lib/util/patterns.js.map +1 -1
  86. package/base/lib/util/regexes.d.ts +38 -0
  87. package/base/lib/util/regexes.js +38 -0
  88. package/base/lib/util/regexes.js.map +1 -1
  89. package/base/lib/util/splitCommand.d.ts +14 -0
  90. package/base/lib/util/splitCommand.js +14 -0
  91. package/base/lib/util/splitCommand.js.map +1 -1
  92. package/base/lib/util/stringFromStdErrOut.d.ts +7 -0
  93. package/base/lib/util/stringFromStdErrOut.js +7 -0
  94. package/base/lib/util/stringFromStdErrOut.js.map +1 -1
  95. package/base/lib/util/typeHelpers.d.ts +35 -0
  96. package/base/lib/util/typeHelpers.js +7 -0
  97. package/base/lib/util/typeHelpers.js.map +1 -1
  98. package/package/lib/StartSdk.d.ts +328 -2
  99. package/package/lib/StartSdk.js +142 -1
  100. package/package/lib/StartSdk.js.map +1 -1
  101. package/package/lib/backup/Backups.d.ts +71 -0
  102. package/package/lib/backup/Backups.js +69 -0
  103. package/package/lib/backup/Backups.js.map +1 -1
  104. package/package/lib/backup/setupBackups.d.ts +14 -0
  105. package/package/lib/backup/setupBackups.js +9 -0
  106. package/package/lib/backup/setupBackups.js.map +1 -1
  107. package/package/lib/health/HealthCheck.d.ts +16 -0
  108. package/package/lib/health/HealthCheck.js +15 -0
  109. package/package/lib/health/HealthCheck.js.map +1 -1
  110. package/package/lib/health/checkFns/HealthCheckResult.d.ts +6 -0
  111. package/package/lib/health/checkFns/index.d.ts +8 -0
  112. package/package/lib/health/checkFns/index.js +8 -0
  113. package/package/lib/health/checkFns/index.js.map +1 -1
  114. package/package/lib/mainFn/CommandController.d.ts +29 -0
  115. package/package/lib/mainFn/CommandController.js +29 -0
  116. package/package/lib/mainFn/CommandController.js.map +1 -1
  117. package/package/lib/mainFn/Daemon.d.ts +38 -2
  118. package/package/lib/mainFn/Daemon.js +38 -2
  119. package/package/lib/mainFn/Daemon.js.map +1 -1
  120. package/package/lib/mainFn/Daemons.d.ts +31 -0
  121. package/package/lib/mainFn/Daemons.js +13 -0
  122. package/package/lib/mainFn/Daemons.js.map +1 -1
  123. package/package/lib/mainFn/Mounts.d.ts +38 -0
  124. package/package/lib/mainFn/Mounts.js +38 -0
  125. package/package/lib/mainFn/Mounts.js.map +1 -1
  126. package/package/lib/mainFn/index.d.ts +1 -0
  127. package/package/lib/mainFn/index.js +1 -0
  128. package/package/lib/mainFn/index.js.map +1 -1
  129. package/package/lib/manifest/setupManifest.d.ts +9 -0
  130. package/package/lib/manifest/setupManifest.js +9 -0
  131. package/package/lib/manifest/setupManifest.js.map +1 -1
  132. package/package/lib/test/output.sdk.d.ts +192 -2
  133. package/package/lib/util/SubContainer.d.ts +46 -0
  134. package/package/lib/util/SubContainer.js +10 -0
  135. package/package/lib/util/SubContainer.js.map +1 -1
  136. package/package/lib/util/fileHelper.d.ts +41 -8
  137. package/package/lib/util/fileHelper.js +6 -4
  138. package/package/lib/util/fileHelper.js.map +1 -1
  139. package/package/lib/version/VersionGraph.d.ts +61 -0
  140. package/package/lib/version/VersionGraph.js +61 -0
  141. package/package/lib/version/VersionGraph.js.map +1 -1
  142. package/package/lib/version/VersionInfo.d.ts +17 -0
  143. package/package/lib/version/VersionInfo.js +12 -0
  144. package/package/lib/version/VersionInfo.js.map +1 -1
  145. package/package/package.json +3 -2
  146. package/package.json +3 -2
@@ -0,0 +1 @@
1
+ export type ServerHostname = string;
@@ -0,0 +1,4 @@
1
+ "use strict";
2
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ //# sourceMappingURL=ServerHostname.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ServerHostname.js","sourceRoot":"","sources":["../../../../base/lib/osBindings/ServerHostname.ts"],"names":[],"mappings":";AAAA,4GAA4G"}
@@ -8,6 +8,7 @@ export type ServerInfo = {
8
8
  arch: string;
9
9
  platform: string;
10
10
  id: string;
11
+ name: string;
11
12
  hostname: string;
12
13
  version: string;
13
14
  packageVersionCompat: string;
@@ -0,0 +1,4 @@
1
+ export type SetServerHostnameParams = {
2
+ name: string | null;
3
+ hostname: string | null;
4
+ };
@@ -0,0 +1,4 @@
1
+ "use strict";
2
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ //# sourceMappingURL=SetServerHostnameParams.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"SetServerHostnameParams.js","sourceRoot":"","sources":["../../../../base/lib/osBindings/SetServerHostnameParams.ts"],"names":[],"mappings":";AAAA,4GAA4G"}
@@ -2,7 +2,9 @@ import type { EncryptedWire } from './EncryptedWire';
2
2
  import type { RecoverySource } from './RecoverySource';
3
3
  export type SetupExecuteParams = {
4
4
  guid: string;
5
- password: EncryptedWire;
5
+ password: EncryptedWire | null;
6
6
  recoverySource: RecoverySource<EncryptedWire> | null;
7
7
  kiosk?: boolean;
8
+ name: string | null;
9
+ hostname: string | null;
8
10
  };
@@ -0,0 +1 @@
1
+ export type SmtpSecurity = 'starttls' | 'tls';
@@ -0,0 +1,4 @@
1
+ "use strict";
2
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ //# sourceMappingURL=SmtpSecurity.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"SmtpSecurity.js","sourceRoot":"","sources":["../../../../base/lib/osBindings/SmtpSecurity.ts"],"names":[],"mappings":";AAAA,4GAA4G"}
@@ -1,7 +1,9 @@
1
+ import type { SmtpSecurity } from './SmtpSecurity';
1
2
  export type SmtpValue = {
2
- server: string;
3
+ host: string;
3
4
  port: number;
4
5
  from: string;
5
- login: string;
6
+ username: string;
6
7
  password: string | null;
8
+ security: SmtpSecurity;
7
9
  };
@@ -1,4 +1,3 @@
1
1
  "use strict";
2
- // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
3
2
  Object.defineProperty(exports, "__esModule", { value: true });
4
3
  //# sourceMappingURL=SmtpValue.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"SmtpValue.js","sourceRoot":"","sources":["../../../../base/lib/osBindings/SmtpValue.ts"],"names":[],"mappings":";AAAA,4GAA4G"}
1
+ {"version":3,"file":"SmtpValue.js","sourceRoot":"","sources":["../../../../base/lib/osBindings/SmtpValue.ts"],"names":[],"mappings":""}
@@ -1,6 +1,6 @@
1
- import type { Hostname } from './Hostname';
1
+ import type { ServerHostname } from './ServerHostname';
2
2
  export type StartOsRecoveryInfo = {
3
- hostname: Hostname;
3
+ hostname: ServerHostname;
4
4
  version: string;
5
5
  timestamp: string;
6
6
  passwordHash: string | null;
@@ -1,8 +1,10 @@
1
+ import type { SmtpSecurity } from './SmtpSecurity';
1
2
  export type TestSmtpParams = {
2
- server: string;
3
+ host: string;
3
4
  port: number;
4
5
  from: string;
5
6
  to: string;
6
- login: string;
7
+ username: string;
7
8
  password: string;
9
+ security: SmtpSecurity;
8
10
  };
@@ -1,4 +1,3 @@
1
1
  "use strict";
2
- // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
3
2
  Object.defineProperty(exports, "__esModule", { value: true });
4
3
  //# sourceMappingURL=TestSmtpParams.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"TestSmtpParams.js","sourceRoot":"","sources":["../../../../base/lib/osBindings/TestSmtpParams.ts"],"names":[],"mappings":";AAAA,4GAA4G"}
1
+ {"version":3,"file":"TestSmtpParams.js","sourceRoot":"","sources":["../../../../base/lib/osBindings/TestSmtpParams.ts"],"names":[],"mappings":""}
@@ -130,7 +130,6 @@ export { HealthCheckId } from './HealthCheckId';
130
130
  export { HostId } from './HostId';
131
131
  export { HostnameInfo } from './HostnameInfo';
132
132
  export { HostnameMetadata } from './HostnameMetadata';
133
- export { Hostname } from './Hostname';
134
133
  export { Hosts } from './Hosts';
135
134
  export { Host } from './Host';
136
135
  export { IdMap } from './IdMap';
@@ -237,6 +236,7 @@ export { RestorePackageParams } from './RestorePackageParams';
237
236
  export { RunActionParams } from './RunActionParams';
238
237
  export { Security } from './Security';
239
238
  export { ServerBackupReport } from './ServerBackupReport';
239
+ export { ServerHostname } from './ServerHostname';
240
240
  export { ServerInfo } from './ServerInfo';
241
241
  export { ServerSpecs } from './ServerSpecs';
242
242
  export { ServerStatus } from './ServerStatus';
@@ -257,6 +257,7 @@ export { SetMainStatusStatus } from './SetMainStatusStatus';
257
257
  export { SetMainStatus } from './SetMainStatus';
258
258
  export { SetNameParams } from './SetNameParams';
259
259
  export { SetOutboundGatewayParams } from './SetOutboundGatewayParams';
260
+ export { SetServerHostnameParams } from './SetServerHostnameParams';
260
261
  export { SetStaticDnsParams } from './SetStaticDnsParams';
261
262
  export { SetupExecuteParams } from './SetupExecuteParams';
262
263
  export { SetupInfo } from './SetupInfo';
@@ -269,6 +270,7 @@ export { SideloadResponse } from './SideloadResponse';
269
270
  export { SignalStrength } from './SignalStrength';
270
271
  export { SignAssetParams } from './SignAssetParams';
271
272
  export { SignerInfo } from './SignerInfo';
273
+ export { SmtpSecurity } from './SmtpSecurity';
272
274
  export { SmtpValue } from './SmtpValue';
273
275
  export { SshAddParams } from './SshAddParams';
274
276
  export { SshDeleteParams } from './SshDeleteParams';
@@ -1,17 +1,83 @@
1
1
  import { DataUrl, Manifest, MerkleArchiveCommitment, PackageId } from '../osBindings';
2
2
  import { MerkleArchive } from './merkleArchive';
3
+ /**
4
+ * Compares two `Uint8Array` instances byte-by-byte for equality.
5
+ *
6
+ * @returns `true` if both arrays have the same length and identical bytes
7
+ */
3
8
  export declare function compare(a: Uint8Array, b: Uint8Array): boolean;
9
+ /**
10
+ * Represents a parsed `.s9pk` package archive — the binary distribution format for StartOS services.
11
+ *
12
+ * An `S9pk` wraps a verified {@link Manifest}, a {@link MerkleArchive} containing the package's
13
+ * assets (icon, license, dependency metadata), and the total archive size in bytes.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * const s9pk = await S9pk.deserialize(file, null)
18
+ * console.log(s9pk.manifest.id) // e.g. "bitcoind"
19
+ * console.log(s9pk.size) // archive size in bytes
20
+ * const icon = await s9pk.icon() // base64 data URL
21
+ * const license = await s9pk.license()
22
+ * ```
23
+ */
4
24
  export declare class S9pk {
25
+ /** The parsed package manifest containing metadata, dependencies, and interface definitions. */
5
26
  readonly manifest: Manifest;
27
+ /** The Merkle-verified archive containing the package's files. */
6
28
  readonly archive: MerkleArchive;
29
+ /** The total size of the archive in bytes. */
7
30
  readonly size: number;
8
31
  private constructor();
32
+ /**
33
+ * Deserializes an `S9pk` from a `Blob` (e.g. a `File` from a browser file input).
34
+ *
35
+ * Validates the magic bytes and version header, then parses the Merkle archive structure.
36
+ * If a `commitment` is provided, the archive is cryptographically verified against it.
37
+ *
38
+ * @param source - The raw `.s9pk` file as a `Blob`
39
+ * @param commitment - An optional Merkle commitment to verify the archive against, or `null` to skip verification
40
+ * @returns A fully parsed `S9pk` instance
41
+ * @throws If the magic bytes are invalid or the archive fails verification
42
+ */
9
43
  static deserialize(source: Blob, commitment: MerkleArchiveCommitment | null): Promise<S9pk>;
44
+ /**
45
+ * Extracts the package icon from the archive and returns it as a base64-encoded data URL.
46
+ *
47
+ * Looks for a file named `icon.*` with an image MIME type (e.g. `icon.png`, `icon.svg`).
48
+ *
49
+ * @returns A data URL string like `"data:image/png;base64,..."` suitable for use in `<img src>`.
50
+ * @throws If no icon file is found in the archive
51
+ */
10
52
  icon(): Promise<DataUrl>;
53
+ /**
54
+ * Returns the metadata (e.g. `{ title }`) for a specific dependency by its package ID.
55
+ *
56
+ * @param id - The dependency's package identifier (e.g. `"bitcoind"`)
57
+ * @returns The dependency metadata object, or `null` if the dependency is not present in the archive
58
+ */
11
59
  dependencyMetadataFor(id: PackageId): Promise<{
12
60
  title: string;
13
61
  } | null>;
62
+ /**
63
+ * Returns the icon for a specific dependency as a base64 data URL.
64
+ *
65
+ * @param id - The dependency's package identifier
66
+ * @returns A data URL string, or `null` if the dependency or its icon is not present
67
+ */
14
68
  dependencyIconFor(id: PackageId): Promise<string | null>;
69
+ /**
70
+ * Returns a merged record of all dependency metadata (title, icon, description, optional flag)
71
+ * for every dependency declared in the manifest.
72
+ *
73
+ * @returns A record keyed by package ID, each containing `{ title, icon, description, optional }`
74
+ */
15
75
  dependencyMetadata(): Promise<any>;
76
+ /**
77
+ * Reads and returns the `LICENSE.md` file from the archive as a UTF-8 string.
78
+ *
79
+ * @returns The full license text
80
+ * @throws If `LICENSE.md` is not found in the archive
81
+ */
16
82
  license(): Promise<string>;
17
83
  }
@@ -10,6 +10,11 @@ const mime_1 = __importDefault(require("mime"));
10
10
  const directoryContents_1 = require("./merkleArchive/directoryContents");
11
11
  const fileContents_1 = require("./merkleArchive/fileContents");
12
12
  const magicAndVersion = new Uint8Array([59, 59, 2]);
13
+ /**
14
+ * Compares two `Uint8Array` instances byte-by-byte for equality.
15
+ *
16
+ * @returns `true` if both arrays have the same length and identical bytes
17
+ */
13
18
  function compare(a, b) {
14
19
  if (a.length !== b.length)
15
20
  return false;
@@ -19,12 +24,44 @@ function compare(a, b) {
19
24
  }
20
25
  return true;
21
26
  }
27
+ /**
28
+ * Represents a parsed `.s9pk` package archive — the binary distribution format for StartOS services.
29
+ *
30
+ * An `S9pk` wraps a verified {@link Manifest}, a {@link MerkleArchive} containing the package's
31
+ * assets (icon, license, dependency metadata), and the total archive size in bytes.
32
+ *
33
+ * @example
34
+ * ```ts
35
+ * const s9pk = await S9pk.deserialize(file, null)
36
+ * console.log(s9pk.manifest.id) // e.g. "bitcoind"
37
+ * console.log(s9pk.size) // archive size in bytes
38
+ * const icon = await s9pk.icon() // base64 data URL
39
+ * const license = await s9pk.license()
40
+ * ```
41
+ */
22
42
  class S9pk {
23
- constructor(manifest, archive, size) {
43
+ constructor(
44
+ /** The parsed package manifest containing metadata, dependencies, and interface definitions. */
45
+ manifest,
46
+ /** The Merkle-verified archive containing the package's files. */
47
+ archive,
48
+ /** The total size of the archive in bytes. */
49
+ size) {
24
50
  this.manifest = manifest;
25
51
  this.archive = archive;
26
52
  this.size = size;
27
53
  }
54
+ /**
55
+ * Deserializes an `S9pk` from a `Blob` (e.g. a `File` from a browser file input).
56
+ *
57
+ * Validates the magic bytes and version header, then parses the Merkle archive structure.
58
+ * If a `commitment` is provided, the archive is cryptographically verified against it.
59
+ *
60
+ * @param source - The raw `.s9pk` file as a `Blob`
61
+ * @param commitment - An optional Merkle commitment to verify the archive against, or `null` to skip verification
62
+ * @returns A fully parsed `S9pk` instance
63
+ * @throws If the magic bytes are invalid or the archive fails verification
64
+ */
28
65
  static async deserialize(source, commitment) {
29
66
  const header = new merkleArchive_1.ArrayBufferReader(await source
30
67
  .slice(0, magicAndVersion.length + merkleArchive_1.MerkleArchive.headerSize)
@@ -39,6 +76,14 @@ class S9pk {
39
76
  ?.verifiedFileContents()));
40
77
  return new S9pk(manifest, archive, source.size);
41
78
  }
79
+ /**
80
+ * Extracts the package icon from the archive and returns it as a base64-encoded data URL.
81
+ *
82
+ * Looks for a file named `icon.*` with an image MIME type (e.g. `icon.png`, `icon.svg`).
83
+ *
84
+ * @returns A data URL string like `"data:image/png;base64,..."` suitable for use in `<img src>`.
85
+ * @throws If no icon file is found in the archive
86
+ */
42
87
  async icon() {
43
88
  const iconName = Object.keys(this.archive.contents.contents).find((name) => name.startsWith('icon.') && mime_1.default.getType(name)?.startsWith('image/'));
44
89
  if (!iconName) {
@@ -47,6 +92,12 @@ class S9pk {
47
92
  return (`data:${mime_1.default.getType(iconName)};base64,` +
48
93
  Buffer.from(await this.archive.contents.getPath([iconName]).verifiedFileContents()).toString('base64'));
49
94
  }
95
+ /**
96
+ * Returns the metadata (e.g. `{ title }`) for a specific dependency by its package ID.
97
+ *
98
+ * @param id - The dependency's package identifier (e.g. `"bitcoind"`)
99
+ * @returns The dependency metadata object, or `null` if the dependency is not present in the archive
100
+ */
50
101
  async dependencyMetadataFor(id) {
51
102
  const entry = this.archive.contents.getPath([
52
103
  'dependencies',
@@ -57,6 +108,12 @@ class S9pk {
57
108
  return null;
58
109
  return JSON.parse(new TextDecoder().decode(await entry.verifiedFileContents()));
59
110
  }
111
+ /**
112
+ * Returns the icon for a specific dependency as a base64 data URL.
113
+ *
114
+ * @param id - The dependency's package identifier
115
+ * @returns A data URL string, or `null` if the dependency or its icon is not present
116
+ */
60
117
  async dependencyIconFor(id) {
61
118
  const dir = this.archive.contents.getPath(['dependencies', id]);
62
119
  if (!dir || !(dir.contents instanceof directoryContents_1.DirectoryContents))
@@ -67,6 +124,12 @@ class S9pk {
67
124
  return (`data:${mime_1.default.getType(iconName)};base64,` +
68
125
  Buffer.from(await dir.contents.getPath([iconName]).verifiedFileContents()).toString('base64'));
69
126
  }
127
+ /**
128
+ * Returns a merged record of all dependency metadata (title, icon, description, optional flag)
129
+ * for every dependency declared in the manifest.
130
+ *
131
+ * @returns A record keyed by package ID, each containing `{ title, icon, description, optional }`
132
+ */
70
133
  async dependencyMetadata() {
71
134
  return Object.fromEntries(await Promise.all(Object.entries(this.manifest.dependencies)
72
135
  .filter(([_, info]) => !!info)
@@ -80,6 +143,12 @@ class S9pk {
80
143
  },
81
144
  ])));
82
145
  }
146
+ /**
147
+ * Reads and returns the `LICENSE.md` file from the archive as a UTF-8 string.
148
+ *
149
+ * @returns The full license text
150
+ * @throws If `LICENSE.md` is not found in the archive
151
+ */
83
152
  async license() {
84
153
  const file = this.archive.contents.getPath(['LICENSE.md']);
85
154
  if (!file || !(file.contents instanceof fileContents_1.FileContents))
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../base/lib/s9pk/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../base/lib/s9pk/index.ts"],"names":[],"mappings":"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"}
@@ -1,4 +1,5 @@
1
1
  export * as inputSpecTypes from './actions/input/inputSpecTypes';
2
+ import { InputSpec as InputSpecClass } from './actions/input/builder/inputSpec';
2
3
  import { DependencyRequirement, NamedHealthCheckResult, Manifest, ServiceInterface, ActionId } from './osBindings';
3
4
  import { StringObject, ToKebab } from './util';
4
5
  import { Action, Actions } from './actions/setupActions';
@@ -8,21 +9,33 @@ export { Effects };
8
9
  export * from './osBindings';
9
10
  export { SDKManifest } from './types/ManifestTypes';
10
11
  export { RequiredDependenciesOf as RequiredDependencies, OptionalDependenciesOf as OptionalDependencies, CurrentDependenciesResult, } from './dependencies/setupDependencies';
12
+ /** An object that can be built into a terminable daemon process. */
11
13
  export type DaemonBuildable = {
12
14
  build(): Promise<{
13
15
  term(): Promise<void>;
14
16
  }>;
15
17
  };
18
+ /** The three categories of service network interfaces. */
16
19
  export type ServiceInterfaceType = 'ui' | 'p2p' | 'api';
20
+ /** A Node.js signal name (e.g. `"SIGTERM"`, `"SIGKILL"`). */
17
21
  export type Signals = NodeJS.Signals;
22
+ /** The SIGTERM signal — used for graceful daemon termination. */
18
23
  export declare const SIGTERM: Signals;
24
+ /** The SIGKILL signal — used for forceful daemon termination. */
19
25
  export declare const SIGKILL: Signals;
26
+ /** Sentinel value (`-1`) indicating that no timeout should be applied. */
20
27
  export declare const NO_TIMEOUT = -1;
28
+ /** A function that builds an absolute file path from a volume name and relative path. */
21
29
  export type PathMaker = (options: {
22
30
  volume: string;
23
31
  path: string;
24
32
  }) => string;
33
+ /** A value that may or may not be wrapped in a `Promise`. */
25
34
  export type MaybePromise<A> = Promise<A> | A;
35
+ /**
36
+ * Namespace defining the required exports for a StartOS service package.
37
+ * Every package must export implementations matching these types.
38
+ */
26
39
  export declare namespace ExpectedExports {
27
40
  /** For backing up service data though the startOS UI */
28
41
  type createBackup = (options: {
@@ -50,9 +63,15 @@ export declare namespace ExpectedExports {
50
63
  effects: Effects;
51
64
  target: ExtendedVersion | VersionRange | null;
52
65
  }) => Promise<unknown>;
66
+ /** The package manifest describing the service's metadata, dependencies, and interfaces. */
53
67
  type manifest = Manifest;
68
+ /** The map of user-invocable actions defined by this service. */
54
69
  type actions = Actions<Record<ActionId, Action<ActionId, any>>>;
55
70
  }
71
+ /**
72
+ * The complete ABI (Application Binary Interface) for a StartOS service package.
73
+ * Maps all required exports to their expected types.
74
+ */
56
75
  export type ABI = {
57
76
  createBackup: ExpectedExports.createBackup;
58
77
  main: ExpectedExports.main;
@@ -61,48 +80,75 @@ export type ABI = {
61
80
  manifest: ExpectedExports.manifest;
62
81
  actions: ExpectedExports.actions;
63
82
  };
83
+ /** A time value in milliseconds. */
64
84
  export type TimeMs = number;
85
+ /** A version string in string form. */
65
86
  export type VersionString = string;
66
87
  declare const DaemonProof: unique symbol;
88
+ /** Opaque branded type proving that a daemon was started. Cannot be constructed directly. */
67
89
  export type DaemonReceipt = {
68
90
  [DaemonProof]: never;
69
91
  };
92
+ /** A running daemon with methods to wait for completion or terminate it. */
70
93
  export type Daemon = {
94
+ /** Waits for the daemon to exit and returns its exit message. */
71
95
  wait(): Promise<string>;
96
+ /** Terminates the daemon. */
72
97
  term(): Promise<null>;
73
98
  [DaemonProof]: never;
74
99
  };
100
+ /** The result status of a health check (extracted from `NamedHealthCheckResult`). */
75
101
  export type HealthStatus = NamedHealthCheckResult['result'];
102
+ /** SMTP mail server configuration values. */
76
103
  export type SmtpValue = {
77
- server: string;
104
+ host: string;
78
105
  port: number;
79
106
  from: string;
80
- login: string;
107
+ username: string;
81
108
  password: string | null | undefined;
109
+ security: 'starttls' | 'tls';
82
110
  };
111
+ /**
112
+ * Marker class indicating that a container should use its own built-in entrypoint
113
+ * rather than a custom command. Optionally accepts an override command array.
114
+ */
83
115
  export declare class UseEntrypoint {
84
116
  readonly overridCmd?: string[] | undefined;
85
117
  readonly USE_ENTRYPOINT = "USE_ENTRYPOINT";
86
118
  constructor(overridCmd?: string[] | undefined);
87
119
  }
120
+ /** Type guard that checks if a {@link CommandType} is a {@link UseEntrypoint} instance. */
88
121
  export declare function isUseEntrypoint(command: CommandType): command is UseEntrypoint;
122
+ /**
123
+ * The ways to specify a command to run in a container:
124
+ * - A shell string (run via `sh -c`)
125
+ * - An explicit argv array
126
+ * - A {@link UseEntrypoint} to use the container's built-in entrypoint
127
+ */
89
128
  export type CommandType = string | [string, ...string[]] | UseEntrypoint;
129
+ /** The return type from starting a daemon — provides `wait()` and `term()` controls. */
90
130
  export type DaemonReturned = {
131
+ /** Waits for the daemon process to exit. */
91
132
  wait(): Promise<unknown>;
133
+ /** Sends a signal to terminate the daemon. If it doesn't exit within `timeout` ms, sends SIGKILL. */
92
134
  term(options?: {
93
135
  signal?: Signals;
94
136
  timeout?: number;
95
137
  }): Promise<null>;
96
138
  };
97
139
  export declare const hostName: unique symbol;
140
+ /** A branded string type for hostnames (e.g. `.onion` addresses or IP addresses). */
98
141
  export type Hostname = string & {
99
142
  [hostName]: never;
100
143
  };
144
+ /** A string identifier for a service network interface. */
101
145
  export type ServiceInterfaceId = string;
102
146
  export { ServiceInterface };
147
+ /** Maps effect method names to their kebab-case RPC equivalents. */
103
148
  export type EffectMethod<T extends StringObject = Effects> = {
104
149
  [K in keyof T]-?: K extends string ? T[K] extends Function ? ToKebab<K> : T[K] extends StringObject ? `${ToKebab<K>}.${EffectMethod<T[K]>}` : never : never;
105
150
  }[keyof T];
151
+ /** Options for rsync-based file synchronization (used in backup/restore). */
106
152
  export type SyncOptions = {
107
153
  /** delete files that exist in the target directory, but not in the source directory */
108
154
  delete: boolean;
@@ -126,33 +172,53 @@ export type Metadata = {
126
172
  gid: number;
127
173
  mode: number;
128
174
  };
175
+ /** Result type for setting a service's dependency configuration and restart signal. */
129
176
  export type SetResult = {
130
177
  dependsOn: DependsOn;
131
178
  signal: Signals;
132
179
  };
180
+ /** A string identifier for a StartOS package (e.g. `"bitcoind"`). */
133
181
  export type PackageId = string;
182
+ /** A user-facing message string. */
134
183
  export type Message = string;
184
+ /** Whether a dependency needs to be actively running or merely installed. */
135
185
  export type DependencyKind = 'running' | 'exists';
186
+ /**
187
+ * Maps package IDs to the health check IDs that must pass before this service considers
188
+ * the dependency satisfied.
189
+ */
136
190
  export type DependsOn = {
137
191
  [packageId: string]: string[] | readonly string[];
138
192
  };
193
+ /**
194
+ * A typed error that can be displayed to the user.
195
+ * Either a plain error message string, or a structured error code with description.
196
+ */
139
197
  export type KnownError = {
140
198
  error: string;
141
199
  } | {
142
200
  errorCode: [number, string] | readonly [number, string];
143
201
  };
202
+ /** An array of dependency requirements for a service. */
144
203
  export type Dependencies = Array<DependencyRequirement>;
204
+ /** Recursively makes all properties of `T` optional. */
145
205
  export type DeepPartial<T> = T extends [infer A, ...infer Rest] ? [DeepPartial<A>, ...DeepPartial<Rest>] : T extends {} ? {
146
206
  [P in keyof T]?: DeepPartial<T[P]>;
147
207
  } : T;
208
+ /** Recursively removes all `readonly` modifiers from `T`. */
148
209
  export type DeepWritable<T> = {
149
210
  -readonly [K in keyof T]: T[K];
150
211
  };
212
+ /** Casts a value to {@link DeepWritable} (identity at runtime, removes `readonly` at the type level). */
151
213
  export declare function writable<T>(value: T): DeepWritable<T>;
214
+ /** Recursively makes all properties of `T` readonly. */
152
215
  export type DeepReadonly<T> = {
153
216
  readonly [P in keyof T]: DeepReadonly<T[P]>;
154
217
  };
218
+ /** Casts a value to {@link DeepReadonly} (identity at runtime, adds `readonly` at the type level). */
155
219
  export declare function readonly<T>(value: T): DeepReadonly<T>;
220
+ /** Accepts either a mutable or deeply-readonly version of `T`. */
156
221
  export type AllowReadonly<T> = T | {
157
222
  readonly [P in keyof T]: AllowReadonly<T[P]>;
158
223
  };
224
+ export type InputSpec<Type extends StaticValidatedAs, StaticValidatedAs extends Record<string, unknown> = Type> = InputSpecClass<Type, StaticValidatedAs>;
package/base/lib/types.js CHANGED
@@ -42,13 +42,24 @@ exports.writable = writable;
42
42
  exports.readonly = readonly;
43
43
  exports.inputSpecTypes = __importStar(require("./actions/input/inputSpecTypes"));
44
44
  __exportStar(require("./osBindings"), exports);
45
+ /** The SIGTERM signal — used for graceful daemon termination. */
45
46
  exports.SIGTERM = 'SIGTERM';
47
+ /** The SIGKILL signal — used for forceful daemon termination. */
46
48
  exports.SIGKILL = 'SIGKILL';
49
+ /** Sentinel value (`-1`) indicating that no timeout should be applied. */
47
50
  exports.NO_TIMEOUT = -1;
51
+ /**
52
+ * Namespace defining the required exports for a StartOS service package.
53
+ * Every package must export implementations matching these types.
54
+ */
48
55
  var ExpectedExports;
49
56
  (function (ExpectedExports) {
50
57
  version: 1;
51
58
  })(ExpectedExports || (exports.ExpectedExports = ExpectedExports = {}));
59
+ /**
60
+ * Marker class indicating that a container should use its own built-in entrypoint
61
+ * rather than a custom command. Optionally accepts an override command array.
62
+ */
52
63
  class UseEntrypoint {
53
64
  constructor(overridCmd) {
54
65
  this.overridCmd = overridCmd;
@@ -56,12 +67,15 @@ class UseEntrypoint {
56
67
  }
57
68
  }
58
69
  exports.UseEntrypoint = UseEntrypoint;
70
+ /** Type guard that checks if a {@link CommandType} is a {@link UseEntrypoint} instance. */
59
71
  function isUseEntrypoint(command) {
60
72
  return typeof command === 'object' && 'USE_ENTRYPOINT' in command;
61
73
  }
74
+ /** Casts a value to {@link DeepWritable} (identity at runtime, removes `readonly` at the type level). */
62
75
  function writable(value) {
63
76
  return value;
64
77
  }
78
+ /** Casts a value to {@link DeepReadonly} (identity at runtime, adds `readonly` at the type level). */
65
79
  function readonly(value) {
66
80
  return value;
67
81
  }
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../base/lib/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,0CAIC;AAmFD,4BAEC;AAMD,4BAEC;AAvMD,iFAAgE;AAchE,+CAA4B;AAgBf,QAAA,OAAO,GAAY,SAAS,CAAA;AAC5B,QAAA,OAAO,GAAY,SAAS,CAAA;AAC5B,QAAA,UAAU,GAAG,CAAC,CAAC,CAAA;AAI5B,IAAiB,eAAe,CA+B/B;AA/BD,WAAiB,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAA;AA8BZ,CAAC,EA/BgB,eAAe,+BAAf,eAAe,QA+B/B;AA+BD,MAAa,aAAa;IAExB,YAAqB,UAAqB;QAArB,eAAU,GAAV,UAAU,CAAW;QADjC,mBAAc,GAAG,gBAAgB,CAAA;IACG,CAAC;CAC/C;AAHD,sCAGC;AACD,SAAgB,eAAe,CAC7B,OAAoB;IAEpB,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,gBAAgB,IAAI,OAAO,CAAA;AACnE,CAAC;AAmFD,SAAgB,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,CAAA;AACd,CAAC;AAMD,SAAgB,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,CAAA;AACd,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../base/lib/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuIA,0CAIC;AA+GD,4BAEC;AAQD,4BAEC;AAtQD,iFAAgE;AAehE,+CAA4B;AAmB5B,iEAAiE;AACpD,QAAA,OAAO,GAAY,SAAS,CAAA;AACzC,iEAAiE;AACpD,QAAA,OAAO,GAAY,SAAS,CAAA;AACzC,0EAA0E;AAC7D,QAAA,UAAU,GAAG,CAAC,CAAC,CAAA;AAM5B;;;GAGG;AACH,IAAiB,eAAe,CAiC/B;AAjCD,WAAiB,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAA;AAgCZ,CAAC,EAjCgB,eAAe,+BAAf,eAAe,QAiC/B;AA4CD;;;GAGG;AACH,MAAa,aAAa;IAExB,YAAqB,UAAqB;QAArB,eAAU,GAAV,UAAU,CAAW;QADjC,mBAAc,GAAG,gBAAgB,CAAA;IACG,CAAC;CAC/C;AAHD,sCAGC;AACD,2FAA2F;AAC3F,SAAgB,eAAe,CAC7B,OAAoB;IAEpB,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,gBAAgB,IAAI,OAAO,CAAA;AACnE,CAAC;AA8GD,yGAAyG;AACzG,SAAgB,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,CAAA;AACd,CAAC;AAOD,sGAAsG;AACtG,SAAgB,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,CAAA;AACd,CAAC"}
@@ -1 +1,9 @@
1
+ /**
2
+ * Converts an unknown thrown value into an Error instance.
3
+ * If `e` is already an Error, wraps it; if a string, uses it as the message;
4
+ * otherwise JSON-serializes it as the error message.
5
+ *
6
+ * @param e - The unknown value to convert
7
+ * @returns An Error instance
8
+ */
1
9
  export declare const asError: (e: unknown) => Error;
@@ -1,6 +1,14 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.asError = void 0;
4
+ /**
5
+ * Converts an unknown thrown value into an Error instance.
6
+ * If `e` is already an Error, wraps it; if a string, uses it as the message;
7
+ * otherwise JSON-serializes it as the error message.
8
+ *
9
+ * @param e - The unknown value to convert
10
+ * @returns An Error instance
11
+ */
4
12
  const asError = (e) => {
5
13
  if (e instanceof Error) {
6
14
  return new Error(e);
@@ -1 +1 @@
1
- {"version":3,"file":"asError.js","sourceRoot":"","sources":["../../../../base/lib/util/asError.ts"],"names":[],"mappings":";;;AAAO,MAAM,OAAO,GAAG,CAAC,CAAU,EAAE,EAAE;IACpC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,IAAI,KAAK,CAAC,CAAQ,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AAC1C,CAAC,CAAA;AARY,QAAA,OAAO,WAQnB"}
1
+ {"version":3,"file":"asError.js","sourceRoot":"","sources":["../../../../base/lib/util/asError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;GAOG;AACI,MAAM,OAAO,GAAG,CAAC,CAAU,EAAE,EAAE;IACpC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,IAAI,KAAK,CAAC,CAAQ,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AAC1C,CAAC,CAAA;AARY,QAAA,OAAO,WAQnB"}