Merge branch 'main' into chore/prepare-release

dfinity · Jan 20, 2025 · 3ab7833 · 3ab7833
2 parents eeb53d6 + 8848c69
commit 3ab7833
Show file tree

Hide file tree

Showing 19 changed files with 365 additions and 13 deletions.
diff --git a/LICENSE b/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/package.json b/package.json
@@ -165,6 +165,16 @@
         "@dfinity/principal"
       ]
     },
+    {
+      "name": "@dfinity/zod-schemas",
+      "path": "./packages/zod-schemas/dist/index.js",
+      "limit": "2 kB",
+      "gzip": true,
+      "ignore": [
+        "zod",
+        "@dfinity/principal"
+      ]
+    },
     {
       "name": "@dfinity/ic-management",
       "path": "./packages/ic-management/dist/index.js",

diff --git a/packages/ckbtc/LICENSE b/packages/ckbtc/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/cketh/LICENSE b/packages/cketh/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/cmc/LICENSE b/packages/cmc/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/ic-management/LICENSE b/packages/ic-management/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/ledger-icp/LICENSE b/packages/ledger-icp/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/ledger-icrc/LICENSE b/packages/ledger-icrc/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/nns-proto/LICENSE b/packages/nns-proto/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/nns/LICENSE b/packages/nns/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/sns/LICENSE b/packages/sns/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/utils/LICENSE b/packages/utils/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/zod-schemas/LICENSE b/packages/zod-schemas/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 DFINITY Stiftung.
+   Copyright 2025 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/packages/zod-schemas/README.md b/packages/zod-schemas/README.md
@@ -29,4 +29,75 @@ npm i @dfinity/principal
 
 <!-- TSDOC_START -->
 
+### :toolbox: Functions
+
+- [createUrlSchema](#gear-createurlschema)
+
+#### :gear: createUrlSchema
+
+Creates a Zod schema for validating URLs. By default, it validates that the URL protocol is HTTPS and allow usage of HTTP only locally.
+
+| Function          | Type                                                                                                                                                                                     |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createUrlSchema` | `({ additionalProtocols, allowHttpLocally, }: { additionalProtocols?: `${string}:`[] or undefined; allowHttpLocally?: boolean or undefined; }) => ZodEffects<ZodString, string, string>` |
+
+Parameters:
+
+- `options`: - Configuration options for the schema.
+- `options.additionalProtocols`: - Additional protocols to allow (e.g., "wss:" or "ftp:"). ⚠️ Usage of insecure protocols is discouraged.
+- `options.allowHttpLocally`: - Whether to allow HTTP for localhost and 127.0.0.1. Default: true.
+
+Examples:
+
+const schema = createUrlSchema({
+additionalProtocols: ["wss:"],
+allowHttpLocally: false
+});
+
+schema.parse("https://example.com"); // Valid
+schema.parse("wss://example.com"); // Valid
+schema.parse("http://localhost"); // Invalid if allowHttpLocally is false
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/zod-schemas/src/url.ts#L27)
+
+### :wrench: Constants
+
+- [PrincipalTextSchema](#gear-principaltextschema)
+- [UrlSchema](#gear-urlschema)
+
+#### :gear: PrincipalTextSchema
+
+Zod schema to validate a string as a valid textual representation of a Principal.
+
+This schema checks if the provided string can be converted into a `Principal` instance.
+If the conversion fails, validation will return an error message.
+
+| Constant              | Type                                    |
+| --------------------- | --------------------------------------- |
+| `PrincipalTextSchema` | `ZodEffects<ZodString, string, string>` |
+
+Examples:
+
+```typescript
+const result = PrincipalTextSchema.safeParse("aaaaa-aa");
+console.log(result.success); // true or false
+```
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/zod-schemas/src/principal.ts#L16)
+
+#### :gear: UrlSchema
+
+Default URL schema that enforces HTTPS and allows HTTP locally.
+
+| Constant    | Type                                    |
+| ----------- | --------------------------------------- |
+| `UrlSchema` | `ZodEffects<ZodString, string, string>` |
+
+Examples:
+
+UrlSchema.parse("https://example.com"); // Valid
+UrlSchema.parse("http://127.0.0.1"); // Valid (localhost exception)
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/zod-schemas/src/url.ts#L70)
+
 <!-- TSDOC_END -->
diff --git a/packages/zod-schemas/src/index.ts b/packages/zod-schemas/src/index.ts
@@ -1 +1,2 @@
-export default {};
+export * from "./principal";
+export * from "./url";
diff --git a/packages/zod-schemas/src/principal.spec.ts b/packages/zod-schemas/src/principal.spec.ts
@@ -0,0 +1,40 @@
+import { Principal } from "@dfinity/principal";
+import { PrincipalTextSchema } from "./principal";
+
+describe("PrincipalText", () => {
+  const mockPrincipalText =
+    "xlmdg-vkosz-ceopx-7wtgu-g3xmd-koiyc-awqaq-7modz-zf6r6-364rh-oqe";
+
+  it("should pass validation with a valid Principal string", () => {
+    const result = PrincipalTextSchema.safeParse(mockPrincipalText);
+    expect(result.success).toBe(true);
+  });
+
+  it("should fail validation with an invalid Principal string", () => {
+    const invalidPrincipal = "invalid-principal";
+    const result = PrincipalTextSchema.safeParse(invalidPrincipal);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.errors[0].message).toBe(
+        "Invalid textual representation of a Principal.",
+      );
+    }
+  });
+
+  it("should pass validation with an anonymous Principal", () => {
+    const validPrincipal = Principal.anonymous().toText();
+    const result = PrincipalTextSchema.safeParse(validPrincipal);
+    expect(result.success).toBe(true);
+  });
+
+  it("should fail validation with a non-string input", () => {
+    const invalidPrincipal = 12345;
+    const result = PrincipalTextSchema.safeParse(invalidPrincipal);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.errors[0].message).toBe(
+        "Expected string, received number",
+      );
+    }
+  });
+});
diff --git a/packages/zod-schemas/src/principal.ts b/packages/zod-schemas/src/principal.ts
@@ -0,0 +1,30 @@
+import { Principal } from "@dfinity/principal";
+import * as z from "zod";
+
+/**
+ * Zod schema to validate a string as a valid textual representation of a Principal.
+ *
+ * This schema checks if the provided string can be converted into a `Principal` instance.
+ * If the conversion fails, validation will return an error message.
+ *
+ * @example
+ * ```typescript
+ * const result = PrincipalTextSchema.safeParse('aaaaa-aa');
+ * console.log(result.success); // true or false
+ * ```
+ */
+export const PrincipalTextSchema = z.string().refine(
+  (principal) => {
+    try {
+      Principal.fromText(principal);
+      return true;
+    } catch (err: unknown) {
+      return false;
+    }
+  },
+  {
+    message: "Invalid textual representation of a Principal.",
+  },
+);
+
+export type PrincipalText = z.infer<typeof PrincipalTextSchema>;