@singi-labs/sifa-sdk 0.12.0 → 0.12.2

package/dist/schemas/write/index.d.cts

@@ -0,0 +1,274 @@
+import { z } from 'zod';
+
+/** Prepend `https://` if no scheme is present. */
+declare function normalizeUrl(val: string): string;
+/**
+ * Accept a URL string or silently drop it if invalid (returns `undefined`).
+ * Preserves the write-time policy: bad URLs from imports are dropped, not rejected.
+ */
+declare const optionalUrl: () => z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+/**
+ * Location shape accepted by the sifa-api write endpoints.
+ *
+ * Accepts BOTH the legacy shape (`id.sifa.defs#locationAddress`: `countryCode`,
+ * `region`, `city`) AND the new community shape
+ * (`community.lexicon.location.address`: `country`, `region`, `locality`,
+ * `street?`, `postalCode?`, `name?`). The frontend reads location records from
+ * the API and echoes them back on save. The API serializer emits explicit `null`
+ * for absent fields (not `undefined`), so every field uses `.nullish()`
+ * (`string | null | undefined`) instead of `.optional()` (`string | undefined`).
+ *
+ * `buildPdsLocation` on the server handles conversion to the PDS shape (always
+ * emitting the new community shape) and returns `undefined` when neither
+ * `country` nor `countryCode` is usable.
+ */
+declare const writeLocationSchema: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+    country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    locality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodString]>>>;
+/** Skill reference: a strong ref to a canonical skill record. */
+declare const skillRefSchema: z.ZodObject<{
+    uri: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Platforms accepted by the external-account write endpoint.
+ *
+ * NOTE: this list intentionally differs from `PLATFORM_LABELS` in the SDK's
+ * `/taxonomy` subpath. `VALID_PLATFORMS` is what sifa-api's `POST /external-accounts`
+ * endpoint enforces; `PLATFORM_LABELS` is the display taxonomy used by the profile
+ * UI. Reconciling them is a separate follow-up (see #TBD). For now the two are
+ * mirrored verbatim from their prior definitions to preserve behavior.
+ */
+declare const VALID_PLATFORMS: readonly ["rss", "fediverse", "twitter", "instagram", "github", "codeberg", "gitlab", "forgejo", "gitea", "youtube", "linkedin", "substack", "website", "orcid", "keyoxide", "other"];
+type ValidPlatform = (typeof VALID_PLATFORMS)[number];
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.certification`. */
+declare const CertificationWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    authority: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    credentialId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    credentialUrl: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    issuedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type CertificationWriteInput = z.infer<typeof CertificationWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.course`. */
+declare const CourseWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    number: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    institution: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type CourseWriteInput = z.infer<typeof CourseWriteSchema>;
+
+/** Schema enforced by `POST /profile/education` on sifa-api. */
+declare const EducationWriteSchema: z.ZodObject<{
+    institution: z.ZodString;
+    degree: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fieldOfStudy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    activities: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type EducationWriteInput = z.infer<typeof EducationWriteSchema>;
+
+/** Schema enforced by `POST /external-accounts` on sifa-api. */
+declare const ExternalAccountWriteSchema: z.ZodObject<{
+    platform: z.ZodEnum<{
+        rss: "rss";
+        fediverse: "fediverse";
+        twitter: "twitter";
+        instagram: "instagram";
+        github: "github";
+        codeberg: "codeberg";
+        gitlab: "gitlab";
+        forgejo: "forgejo";
+        gitea: "gitea";
+        youtube: "youtube";
+        linkedin: "linkedin";
+        substack: "substack";
+        website: "website";
+        orcid: "orcid";
+        keyoxide: "keyoxide";
+        other: "other";
+    }>;
+    url: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    feedUrl: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>>;
+}, z.core.$strip>;
+type ExternalAccountWriteInput = z.infer<typeof ExternalAccountWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.honor`. */
+declare const HonorWriteSchema: z.ZodObject<{
+    title: z.ZodString;
+    issuer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    awardedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type HonorWriteInput = z.infer<typeof HonorWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.language`. */
+declare const LanguageWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    proficiency: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LanguageWriteInput = z.infer<typeof LanguageWriteSchema>;
+
+/**
+ * Schema enforced by `POST /profile/positions` on sifa-api.
+ *
+ * Client-side callers can `.safeParse(...)` this before submitting to catch
+ * obvious problems (empty `title`, over-length text) before the network
+ * round-trip. If it passes here, the API will accept the write modulo
+ * transport / auth failures.
+ *
+ * `company` is intentionally optional to support freelancer / independent
+ * employment types where the position has no employer. The current
+ * `sifa-api/src/routes/schemas.ts` requires `company` (`.min(1)`); the
+ * sifa-api adoption PR that consumes this schema will therefore be a
+ * behavior change that unblocks the freelancer flow. The SDK's lexicon
+ * schema (`ProfilePositionRecordSchema`) has treated `company` as optional
+ * since sifa-sdk #184.
+ */
+declare const PositionWriteSchema: z.ZodObject<{
+    company: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    employmentType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workplaceType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    location: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodString]>>>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    skills: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type PositionWriteInput = z.infer<typeof PositionWriteSchema>;
+
+/**
+ * Schema enforced by `POST /profile/locations` on sifa-api.
+ *
+ * Mirrors the inner object of `writeLocationSchema`: accepts both the community
+ * shape (`country`, `locality`) and the legacy shape (`countryCode`, `city`)
+ * during the dual-read window. sifa-web #840 switched outbound writes to the
+ * community shape; older clients may still send the legacy shape. All address
+ * fields are `.nullish()` so explicit `null` from API echoes is accepted
+ * (see sifa-api #426).
+ *
+ * The route handler hands `address` to `buildPdsLocation`, which normalizes
+ * either input and enforces alpha-2 on the wire to PDS — returning a 400 with
+ * `message: "address.country (alpha-2) is required"` when no usable code is
+ * present. The schema stays permissive on country length here and lets
+ * `buildPdsLocation` be the single enforcement point.
+ */
+declare const ProfileLocationWriteSchema: z.ZodObject<{
+    address: z.ZodObject<{
+        country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    type: z.ZodString;
+    label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    isPrimary: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ProfileLocationWriteInput = z.infer<typeof ProfileLocationWriteSchema>;
+
+/**
+ * Schema enforced by `POST /profile/self` on sifa-api.
+ *
+ * `.passthrough()` so the API accepts fields not yet enumerated here (used for
+ * gradual rollout of new profile-self keys without requiring lockstep bumps
+ * between web/api). Note this means client validation on this schema will
+ * NEVER reject "unknown" fields — the divergence is intentional.
+ *
+ * Grapheme caps (e.g. 64 on given/familyName) are enforced client-side by the
+ * SDK's lexicon schema; the write schema only guards the byte-length ceiling.
+ */
+declare const ProfileSelfWriteSchema: z.ZodObject<{
+    headline: z.ZodOptional<z.ZodString>;
+    about: z.ZodOptional<z.ZodString>;
+    givenName: z.ZodOptional<z.ZodString>;
+    familyName: z.ZodOptional<z.ZodString>;
+    industries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        industry: z.ZodString;
+        domain: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    location: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodString]>>>;
+    openTo: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    preferredWorkplace: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    availableFromUtc: z.ZodOptional<z.ZodNumber>;
+    availableToUtc: z.ZodOptional<z.ZodNumber>;
+    langs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    discoverable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+type ProfileSelfWriteInput = z.infer<typeof ProfileSelfWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.project`. */
+declare const ProjectWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type ProjectWriteInput = z.infer<typeof ProjectWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.publication`. */
+declare const PublicationWriteSchema: z.ZodObject<{
+    title: z.ZodString;
+    publisher: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    publishedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type PublicationWriteInput = z.infer<typeof PublicationWriteSchema>;
+
+/** Schema enforced by `POST /profile/skills` on sifa-api. */
+declare const SkillWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SkillWriteInput = z.infer<typeof SkillWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.volunteering`. */
+declare const VolunteeringWriteSchema: z.ZodObject<{
+    organization: z.ZodString;
+    role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cause: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type VolunteeringWriteInput = z.infer<typeof VolunteeringWriteSchema>;
+
+export { type CertificationWriteInput, CertificationWriteSchema, type CourseWriteInput, CourseWriteSchema, type EducationWriteInput, EducationWriteSchema, type ExternalAccountWriteInput, ExternalAccountWriteSchema, type HonorWriteInput, HonorWriteSchema, type LanguageWriteInput, LanguageWriteSchema, type PositionWriteInput, PositionWriteSchema, type ProfileLocationWriteInput, ProfileLocationWriteSchema, type ProfileSelfWriteInput, ProfileSelfWriteSchema, type ProjectWriteInput, ProjectWriteSchema, type PublicationWriteInput, PublicationWriteSchema, type SkillWriteInput, SkillWriteSchema, VALID_PLATFORMS, type ValidPlatform, type VolunteeringWriteInput, VolunteeringWriteSchema, normalizeUrl, optionalUrl, skillRefSchema, writeLocationSchema };

package/dist/schemas/write/index.d.ts

@@ -0,0 +1,274 @@
+import { z } from 'zod';
+
+/** Prepend `https://` if no scheme is present. */
+declare function normalizeUrl(val: string): string;
+/**
+ * Accept a URL string or silently drop it if invalid (returns `undefined`).
+ * Preserves the write-time policy: bad URLs from imports are dropped, not rejected.
+ */
+declare const optionalUrl: () => z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+/**
+ * Location shape accepted by the sifa-api write endpoints.
+ *
+ * Accepts BOTH the legacy shape (`id.sifa.defs#locationAddress`: `countryCode`,
+ * `region`, `city`) AND the new community shape
+ * (`community.lexicon.location.address`: `country`, `region`, `locality`,
+ * `street?`, `postalCode?`, `name?`). The frontend reads location records from
+ * the API and echoes them back on save. The API serializer emits explicit `null`
+ * for absent fields (not `undefined`), so every field uses `.nullish()`
+ * (`string | null | undefined`) instead of `.optional()` (`string | undefined`).
+ *
+ * `buildPdsLocation` on the server handles conversion to the PDS shape (always
+ * emitting the new community shape) and returns `undefined` when neither
+ * `country` nor `countryCode` is usable.
+ */
+declare const writeLocationSchema: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+    country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    locality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodString]>>>;
+/** Skill reference: a strong ref to a canonical skill record. */
+declare const skillRefSchema: z.ZodObject<{
+    uri: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Platforms accepted by the external-account write endpoint.
+ *
+ * NOTE: this list intentionally differs from `PLATFORM_LABELS` in the SDK's
+ * `/taxonomy` subpath. `VALID_PLATFORMS` is what sifa-api's `POST /external-accounts`
+ * endpoint enforces; `PLATFORM_LABELS` is the display taxonomy used by the profile
+ * UI. Reconciling them is a separate follow-up (see #TBD). For now the two are
+ * mirrored verbatim from their prior definitions to preserve behavior.
+ */
+declare const VALID_PLATFORMS: readonly ["rss", "fediverse", "twitter", "instagram", "github", "codeberg", "gitlab", "forgejo", "gitea", "youtube", "linkedin", "substack", "website", "orcid", "keyoxide", "other"];
+type ValidPlatform = (typeof VALID_PLATFORMS)[number];
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.certification`. */
+declare const CertificationWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    authority: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    credentialId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    credentialUrl: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    issuedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type CertificationWriteInput = z.infer<typeof CertificationWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.course`. */
+declare const CourseWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    number: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    institution: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type CourseWriteInput = z.infer<typeof CourseWriteSchema>;
+
+/** Schema enforced by `POST /profile/education` on sifa-api. */
+declare const EducationWriteSchema: z.ZodObject<{
+    institution: z.ZodString;
+    degree: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fieldOfStudy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    activities: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type EducationWriteInput = z.infer<typeof EducationWriteSchema>;
+
+/** Schema enforced by `POST /external-accounts` on sifa-api. */
+declare const ExternalAccountWriteSchema: z.ZodObject<{
+    platform: z.ZodEnum<{
+        rss: "rss";
+        fediverse: "fediverse";
+        twitter: "twitter";
+        instagram: "instagram";
+        github: "github";
+        codeberg: "codeberg";
+        gitlab: "gitlab";
+        forgejo: "forgejo";
+        gitea: "gitea";
+        youtube: "youtube";
+        linkedin: "linkedin";
+        substack: "substack";
+        website: "website";
+        orcid: "orcid";
+        keyoxide: "keyoxide";
+        other: "other";
+    }>;
+    url: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    feedUrl: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>>;
+}, z.core.$strip>;
+type ExternalAccountWriteInput = z.infer<typeof ExternalAccountWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.honor`. */
+declare const HonorWriteSchema: z.ZodObject<{
+    title: z.ZodString;
+    issuer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    awardedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type HonorWriteInput = z.infer<typeof HonorWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.language`. */
+declare const LanguageWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    proficiency: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LanguageWriteInput = z.infer<typeof LanguageWriteSchema>;
+
+/**
+ * Schema enforced by `POST /profile/positions` on sifa-api.
+ *
+ * Client-side callers can `.safeParse(...)` this before submitting to catch
+ * obvious problems (empty `title`, over-length text) before the network
+ * round-trip. If it passes here, the API will accept the write modulo
+ * transport / auth failures.
+ *
+ * `company` is intentionally optional to support freelancer / independent
+ * employment types where the position has no employer. The current
+ * `sifa-api/src/routes/schemas.ts` requires `company` (`.min(1)`); the
+ * sifa-api adoption PR that consumes this schema will therefore be a
+ * behavior change that unblocks the freelancer flow. The SDK's lexicon
+ * schema (`ProfilePositionRecordSchema`) has treated `company` as optional
+ * since sifa-sdk #184.
+ */
+declare const PositionWriteSchema: z.ZodObject<{
+    company: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    employmentType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workplaceType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    location: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodString]>>>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    skills: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type PositionWriteInput = z.infer<typeof PositionWriteSchema>;
+
+/**
+ * Schema enforced by `POST /profile/locations` on sifa-api.
+ *
+ * Mirrors the inner object of `writeLocationSchema`: accepts both the community
+ * shape (`country`, `locality`) and the legacy shape (`countryCode`, `city`)
+ * during the dual-read window. sifa-web #840 switched outbound writes to the
+ * community shape; older clients may still send the legacy shape. All address
+ * fields are `.nullish()` so explicit `null` from API echoes is accepted
+ * (see sifa-api #426).
+ *
+ * The route handler hands `address` to `buildPdsLocation`, which normalizes
+ * either input and enforces alpha-2 on the wire to PDS — returning a 400 with
+ * `message: "address.country (alpha-2) is required"` when no usable code is
+ * present. The schema stays permissive on country length here and lets
+ * `buildPdsLocation` be the single enforcement point.
+ */
+declare const ProfileLocationWriteSchema: z.ZodObject<{
+    address: z.ZodObject<{
+        country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    type: z.ZodString;
+    label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    isPrimary: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ProfileLocationWriteInput = z.infer<typeof ProfileLocationWriteSchema>;
+
+/**
+ * Schema enforced by `POST /profile/self` on sifa-api.
+ *
+ * `.passthrough()` so the API accepts fields not yet enumerated here (used for
+ * gradual rollout of new profile-self keys without requiring lockstep bumps
+ * between web/api). Note this means client validation on this schema will
+ * NEVER reject "unknown" fields — the divergence is intentional.
+ *
+ * Grapheme caps (e.g. 64 on given/familyName) are enforced client-side by the
+ * SDK's lexicon schema; the write schema only guards the byte-length ceiling.
+ */
+declare const ProfileSelfWriteSchema: z.ZodObject<{
+    headline: z.ZodOptional<z.ZodString>;
+    about: z.ZodOptional<z.ZodString>;
+    givenName: z.ZodOptional<z.ZodString>;
+    familyName: z.ZodOptional<z.ZodString>;
+    industries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        industry: z.ZodString;
+        domain: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    location: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodString]>>>;
+    openTo: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    preferredWorkplace: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    availableFromUtc: z.ZodOptional<z.ZodNumber>;
+    availableToUtc: z.ZodOptional<z.ZodNumber>;
+    langs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    discoverable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+type ProfileSelfWriteInput = z.infer<typeof ProfileSelfWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.project`. */
+declare const ProjectWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type ProjectWriteInput = z.infer<typeof ProjectWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.publication`. */
+declare const PublicationWriteSchema: z.ZodObject<{
+    title: z.ZodString;
+    publisher: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    publishedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type PublicationWriteInput = z.infer<typeof PublicationWriteSchema>;
+
+/** Schema enforced by `POST /profile/skills` on sifa-api. */
+declare const SkillWriteSchema: z.ZodObject<{
+    name: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SkillWriteInput = z.infer<typeof SkillWriteSchema>;
+
+/** Schema enforced by the generic-record write endpoint for `id.sifa.profile.volunteering`. */
+declare const VolunteeringWriteSchema: z.ZodObject<{
+    organization: z.ZodString;
+    role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cause: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type VolunteeringWriteInput = z.infer<typeof VolunteeringWriteSchema>;
+
+export { type CertificationWriteInput, CertificationWriteSchema, type CourseWriteInput, CourseWriteSchema, type EducationWriteInput, EducationWriteSchema, type ExternalAccountWriteInput, ExternalAccountWriteSchema, type HonorWriteInput, HonorWriteSchema, type LanguageWriteInput, LanguageWriteSchema, type PositionWriteInput, PositionWriteSchema, type ProfileLocationWriteInput, ProfileLocationWriteSchema, type ProfileSelfWriteInput, ProfileSelfWriteSchema, type ProjectWriteInput, ProjectWriteSchema, type PublicationWriteInput, PublicationWriteSchema, type SkillWriteInput, SkillWriteSchema, VALID_PLATFORMS, type ValidPlatform, type VolunteeringWriteInput, VolunteeringWriteSchema, normalizeUrl, optionalUrl, skillRefSchema, writeLocationSchema };