@singi-labs/sifa-sdk 0.11.13 → 0.11.14

package/README.md

@@ -89,6 +89,49 @@ pnpm lint
 pnpm typecheck
 ```
 
+### Testing your changes
+
+For SDK logic in isolation (schemas, formatters, taxonomies, fetchers), write a
+test and run the watcher. No consumer app needed:
+
+```bash
+pnpm test:watch
+```
+
+To test a change end-to-end inside a consumer (sifa-web, sifa-api), link your
+local build in. The SDK ships its compiled `dist/`, not source, so keep a build
+running while you edit:
+
+```bash
+pnpm dev   # tsup --watch, rebuilds dist/ on save
+```
+
+Then point the consumer at your checkout. For a pnpm consumer (sifa-web), an
+override is more reproducible across installs than a bare `pnpm link`:
+
+```jsonc
+// consumer package.json
+"pnpm": { "overrides": { "@singi-labs/sifa-sdk": "link:../sifa-sdk" } }
+```
+
+then `pnpm install`. For an npm consumer (sifa-api), `npm link` works.
+
+`react` and `@tanstack/react-query` are optional peer dependencies. If a linked
+build throws "Invalid hook call" or a missing QueryClient, the consumer is
+resolving two copies of them: run `pnpm dedupe`, or add an override pinning both
+to a single version. Only the `./query/hooks` export needs React, so non-React
+consumers like sifa-api never hit this.
+
+For a publish-faithful check with no watch, pack a tarball instead of linking:
+
+```bash
+pnpm build && pnpm pack   # produces singi-labs-sifa-sdk-x.y.z.tgz
+```
+
+then `pnpm add ./singi-labs-sifa-sdk-x.y.z.tgz` in the consumer. This installs
+exactly what would publish (respects `files: ["dist"]`), with no symlink
+resolution quirks.
+
 Standards:
 
 - Strict TypeScript -- `strict: true`, no `any`

package/dist/{feed-DHTy7fUN.d.cts → feed-BaHtJXYR.d.cts}

@@ -1,5 +1,102 @@
 import { z } from 'zod';
 
+/**
+ * A single typeahead row. Discriminated on `source`: a curated `entity` row
+ * carries `entityId`, a `pdl` staging row carries `pdlId`. The union guarantees
+ * the identifier for the row's source is always present, so a stable React key
+ * can never be `entity:undefined`. The disambiguation fields
+ * (domain/country/parentName) drive the dropdown display.
+ */
+declare const EntitySearchResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodString;
+    name: z.ZodString;
+    domain: z.ZodNullable<z.ZodString>;
+    country: z.ZodNullable<z.ZodString>;
+    logoUrl: z.ZodNullable<z.ZodString>;
+    parentName: z.ZodNullable<z.ZodString>;
+    source: z.ZodLiteral<"entity">;
+    entityId: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodString;
+    name: z.ZodString;
+    domain: z.ZodNullable<z.ZodString>;
+    country: z.ZodNullable<z.ZodString>;
+    logoUrl: z.ZodNullable<z.ZodString>;
+    parentName: z.ZodNullable<z.ZodString>;
+    source: z.ZodLiteral<"pdl">;
+    pdlId: z.ZodString;
+}, z.core.$strip>], "source">;
+type EntitySearchResult = z.infer<typeof EntitySearchResultSchema>;
+/** Response of `GET /api/entities/search`. */
+declare const EntitySearchResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+        logoUrl: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"entity">;
+        entityId: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+        logoUrl: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"pdl">;
+        pdlId: z.ZodString;
+    }, z.core.$strip>], "source">>;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+type EntitySearchResponse = z.infer<typeof EntitySearchResponseSchema>;
+/**
+ * Body of `POST /api/entities/select`: promote a PDL row OR bump an entity.
+ * Exactly one of `entityId`/`pdlId` must be present -- supplying both is
+ * ambiguous (the server would have to silently pick one) and is rejected.
+ */
+declare const EntitySelectRequestSchema: z.ZodObject<{
+    entityId: z.ZodOptional<z.ZodNumber>;
+    pdlId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type EntitySelectRequest = z.infer<typeof EntitySelectRequestSchema>;
+/** Response of `POST /api/entities/select`. `entityRef` is the portable
+ * Wikidata/ROR/LEI URI to write to the position record, or null for a
+ * PDL-only entity (its resolution stays AppView-side). */
+declare const EntitySelectResponseSchema: z.ZodObject<{
+    entityId: z.ZodNumber;
+    slug: z.ZodString;
+    kind: z.ZodString;
+    canonicalName: z.ZodString;
+    domain: z.ZodNullable<z.ZodString>;
+    entityRef: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type EntitySelectResponse = z.infer<typeof EntitySelectResponseSchema>;
+/** Response of `POST /api/entities/import-search`. */
+declare const EntityImportSearchResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+        logoUrl: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"entity">;
+        entityId: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+        logoUrl: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"pdl">;
+        pdlId: z.ZodString;
+    }, z.core.$strip>], "source">>;
+}, z.core.$strip>;
+type EntityImportSearchResponse = z.infer<typeof EntityImportSearchResponseSchema>;
+
 /**
  * Profile row shared across `/api/following`, `/api/profile/:handleOrDid/mutuals`,
  * and `/api/me/bluesky-suggestions`. Matches the existing `FollowProfile` TS
@@ -251,4 +348,4 @@ interface FeedCursor {
 declare function encodeFeedCursor(cursor: FeedCursor): string;
 declare function decodeFeedCursor(encoded: string): FeedCursor;
 
-export { type AtmosphereFeedItem as A, type FollowFeedPage as F, type SifaFeedItem as S, type FollowProfileItem as a, type FeatureAllowlistEntry as b, type FeatureFlag as c, AtmosphereFeedItemSchema as d, FEATURE_FLAGS as e, FeatureAllowlistEntrySchema as f, type FeedActor as g, FeedActorSchema as h, type FeedCursor as i, type FollowFeedItem as j, FollowFeedItemSchema as k, FollowFeedPageSchema as l, type FollowProfilePage as m, FollowProfilePageSchema as n, FollowProfileSchema as o, SifaFeedItemSchema as p, decodeFeedCursor as q, encodeFeedCursor as r };
+export { type AtmosphereFeedItem as A, encodeFeedCursor as B, type EntitySearchResult as E, type FollowFeedPage as F, type SifaFeedItem as S, type FollowProfileItem as a, type FeatureAllowlistEntry as b, type FeatureFlag as c, AtmosphereFeedItemSchema as d, type EntityImportSearchResponse as e, EntityImportSearchResponseSchema as f, type EntitySearchResponse as g, EntitySearchResponseSchema as h, EntitySearchResultSchema as i, type EntitySelectRequest as j, EntitySelectRequestSchema as k, type EntitySelectResponse as l, EntitySelectResponseSchema as m, FEATURE_FLAGS as n, FeatureAllowlistEntrySchema as o, type FeedActor as p, FeedActorSchema as q, type FeedCursor as r, type FollowFeedItem as s, FollowFeedItemSchema as t, FollowFeedPageSchema as u, type FollowProfilePage as v, FollowProfilePageSchema as w, FollowProfileSchema as x, SifaFeedItemSchema as y, decodeFeedCursor as z };

package/dist/{feed-DHTy7fUN.d.ts → feed-BaHtJXYR.d.ts}

@@ -1,5 +1,102 @@
 import { z } from 'zod';
 
+/**
+ * A single typeahead row. Discriminated on `source`: a curated `entity` row
+ * carries `entityId`, a `pdl` staging row carries `pdlId`. The union guarantees
+ * the identifier for the row's source is always present, so a stable React key
+ * can never be `entity:undefined`. The disambiguation fields
+ * (domain/country/parentName) drive the dropdown display.
+ */
+declare const EntitySearchResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodString;
+    name: z.ZodString;
+    domain: z.ZodNullable<z.ZodString>;
+    country: z.ZodNullable<z.ZodString>;
+    logoUrl: z.ZodNullable<z.ZodString>;
+    parentName: z.ZodNullable<z.ZodString>;
+    source: z.ZodLiteral<"entity">;
+    entityId: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodString;
+    name: z.ZodString;
+    domain: z.ZodNullable<z.ZodString>;
+    country: z.ZodNullable<z.ZodString>;
+    logoUrl: z.ZodNullable<z.ZodString>;
+    parentName: z.ZodNullable<z.ZodString>;
+    source: z.ZodLiteral<"pdl">;
+    pdlId: z.ZodString;
+}, z.core.$strip>], "source">;
+type EntitySearchResult = z.infer<typeof EntitySearchResultSchema>;
+/** Response of `GET /api/entities/search`. */
+declare const EntitySearchResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+        logoUrl: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"entity">;
+        entityId: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+        logoUrl: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"pdl">;
+        pdlId: z.ZodString;
+    }, z.core.$strip>], "source">>;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+type EntitySearchResponse = z.infer<typeof EntitySearchResponseSchema>;
+/**
+ * Body of `POST /api/entities/select`: promote a PDL row OR bump an entity.
+ * Exactly one of `entityId`/`pdlId` must be present -- supplying both is
+ * ambiguous (the server would have to silently pick one) and is rejected.
+ */
+declare const EntitySelectRequestSchema: z.ZodObject<{
+    entityId: z.ZodOptional<z.ZodNumber>;
+    pdlId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type EntitySelectRequest = z.infer<typeof EntitySelectRequestSchema>;
+/** Response of `POST /api/entities/select`. `entityRef` is the portable
+ * Wikidata/ROR/LEI URI to write to the position record, or null for a
+ * PDL-only entity (its resolution stays AppView-side). */
+declare const EntitySelectResponseSchema: z.ZodObject<{
+    entityId: z.ZodNumber;
+    slug: z.ZodString;
+    kind: z.ZodString;
+    canonicalName: z.ZodString;
+    domain: z.ZodNullable<z.ZodString>;
+    entityRef: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type EntitySelectResponse = z.infer<typeof EntitySelectResponseSchema>;
+/** Response of `POST /api/entities/import-search`. */
+declare const EntityImportSearchResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+        logoUrl: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"entity">;
+        entityId: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodString;
+        name: z.ZodString;
+        domain: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+        logoUrl: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        source: z.ZodLiteral<"pdl">;
+        pdlId: z.ZodString;
+    }, z.core.$strip>], "source">>;
+}, z.core.$strip>;
+type EntityImportSearchResponse = z.infer<typeof EntityImportSearchResponseSchema>;
+
 /**
  * Profile row shared across `/api/following`, `/api/profile/:handleOrDid/mutuals`,
  * and `/api/me/bluesky-suggestions`. Matches the existing `FollowProfile` TS
@@ -251,4 +348,4 @@ interface FeedCursor {
 declare function encodeFeedCursor(cursor: FeedCursor): string;
 declare function decodeFeedCursor(encoded: string): FeedCursor;
 
-export { type AtmosphereFeedItem as A, type FollowFeedPage as F, type SifaFeedItem as S, type FollowProfileItem as a, type FeatureAllowlistEntry as b, type FeatureFlag as c, AtmosphereFeedItemSchema as d, FEATURE_FLAGS as e, FeatureAllowlistEntrySchema as f, type FeedActor as g, FeedActorSchema as h, type FeedCursor as i, type FollowFeedItem as j, FollowFeedItemSchema as k, FollowFeedPageSchema as l, type FollowProfilePage as m, FollowProfilePageSchema as n, FollowProfileSchema as o, SifaFeedItemSchema as p, decodeFeedCursor as q, encodeFeedCursor as r };
+export { type AtmosphereFeedItem as A, encodeFeedCursor as B, type EntitySearchResult as E, type FollowFeedPage as F, type SifaFeedItem as S, type FollowProfileItem as a, type FeatureAllowlistEntry as b, type FeatureFlag as c, AtmosphereFeedItemSchema as d, type EntityImportSearchResponse as e, EntityImportSearchResponseSchema as f, type EntitySearchResponse as g, EntitySearchResponseSchema as h, EntitySearchResultSchema as i, type EntitySelectRequest as j, EntitySelectRequestSchema as k, type EntitySelectResponse as l, EntitySelectResponseSchema as m, FEATURE_FLAGS as n, FeatureAllowlistEntrySchema as o, type FeedActor as p, FeedActorSchema as q, type FeedCursor as r, type FollowFeedItem as s, FollowFeedItemSchema as t, FollowFeedPageSchema as u, type FollowProfilePage as v, FollowProfilePageSchema as w, FollowProfileSchema as x, SifaFeedItemSchema as y, decodeFeedCursor as z };

package/dist/index.cjs

@@ -2404,6 +2404,56 @@ function pickPrimaryPosition(positions) {
   if (flagged) return flagged;
   return [...active].sort((a, b) => (b.startedAt ?? "").localeCompare(a.startedAt ?? ""))[0];
 }
+
+// src/logic/pseudo-employer.ts
+var PSEUDO_EMPLOYERS = /* @__PURE__ */ new Set([
+  "self",
+  "self employed",
+  "selfemployed",
+  "self employment",
+  "self employed freelance",
+  "freelance",
+  "freelancer",
+  "freelancing",
+  "freelance work",
+  "independent",
+  "independent contractor",
+  "independent consultant",
+  "independent professional",
+  "sole proprietor",
+  "sole proprietorship",
+  "sole trader",
+  "own business",
+  "my own business",
+  "self employed consultant"
+]);
+function normalizePseudo(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().replace(/\s+/g, " ");
+}
+function isPseudoEmployer(company) {
+  const normalized = normalizePseudo(company);
+  if (!normalized) return false;
+  return PSEUDO_EMPLOYERS.has(normalized);
+}
+
+// src/logic/entity-disambiguation.ts
+function entityDisambiguationLabel(fields) {
+  const parts = [];
+  if (fields.domain) parts.push(fields.domain);
+  if (fields.country) parts.push(fields.country);
+  if (fields.parentName) parts.push(`part of ${fields.parentName}`);
+  return parts.join(" \xB7 ");
+}
+function searchResultDisambiguation(result) {
+  return entityDisambiguationLabel({
+    domain: result.domain,
+    country: result.country,
+    parentName: result.parentName
+  });
+}
+function entityResultKey(result) {
+  return result.source === "entity" ? `entity:${result.entityId}` : `pdl:${result.pdlId}`;
+}
 function maxGraphemes(max) {
   return (value) => {
     const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
@@ -2439,6 +2489,48 @@ var EndorsementConfirmationRecordSchema = zod.z.object({
   endorsement: strongRefSchema,
   createdAt: datetimeSchema
 });
+var httpUrlNullable = zod.z.string().refine((s) => /^https?:\/\//i.test(s), { message: "must be an http(s) URL" }).nullable();
+var searchResultCommon = {
+  kind: zod.z.string(),
+  name: zod.z.string(),
+  domain: zod.z.string().nullable(),
+  country: zod.z.string().nullable(),
+  logoUrl: httpUrlNullable,
+  parentName: zod.z.string().nullable()
+};
+var EntitySearchResultSchema = zod.z.discriminatedUnion("source", [
+  zod.z.object({
+    source: zod.z.literal("entity"),
+    entityId: zod.z.number().int().positive(),
+    ...searchResultCommon
+  }),
+  zod.z.object({
+    source: zod.z.literal("pdl"),
+    pdlId: zod.z.string().min(1),
+    ...searchResultCommon
+  })
+]);
+var EntitySearchResponseSchema = zod.z.object({
+  results: zod.z.array(EntitySearchResultSchema),
+  hasMore: zod.z.boolean()
+});
+var EntitySelectRequestSchema = zod.z.object({
+  entityId: zod.z.number().int().positive().optional(),
+  pdlId: zod.z.string().min(1).optional()
+}).refine((v) => v.entityId != null !== (v.pdlId != null), {
+  message: "exactly one of entityId or pdlId is required"
+});
+var EntitySelectResponseSchema = zod.z.object({
+  entityId: zod.z.number().int().positive(),
+  slug: zod.z.string(),
+  kind: zod.z.string(),
+  canonicalName: zod.z.string(),
+  domain: zod.z.string().nullable(),
+  entityRef: httpUrlNullable
+});
+var EntityImportSearchResponseSchema = zod.z.object({
+  results: zod.z.array(EntitySearchResultSchema)
+});
 var EndorsementRecordSchema = zod.z.object({
   subject: didSchema,
   skill: strongRefSchema,
@@ -2705,7 +2797,7 @@ var ProfileVolunteeringRecordSchema = zod.z.object({
 });
 
 // src/index.ts
-var SIFA_SDK_VERSION = "0.11.13";
+var SIFA_SDK_VERSION = "0.11.14";
 
 exports.ACTIVITY_TIERS = ACTIVITY_TIERS;
 exports.ACTIVITY_VISIBILITY_RULES = ACTIVITY_VISIBILITY_RULES;
@@ -2729,6 +2821,11 @@ exports.EMPLOYMENT_TYPE_GROUPS = EMPLOYMENT_TYPE_GROUPS;
 exports.EMPLOYMENT_TYPE_LABELS = EMPLOYMENT_TYPE_LABELS;
 exports.EndorsementConfirmationRecordSchema = EndorsementConfirmationRecordSchema;
 exports.EndorsementRecordSchema = EndorsementRecordSchema;
+exports.EntityImportSearchResponseSchema = EntityImportSearchResponseSchema;
+exports.EntitySearchResponseSchema = EntitySearchResponseSchema;
+exports.EntitySearchResultSchema = EntitySearchResultSchema;
+exports.EntitySelectRequestSchema = EntitySelectRequestSchema;
+exports.EntitySelectResponseSchema = EntitySelectResponseSchema;
 exports.FEATURE_FLAGS = FEATURE_FLAGS;
 exports.FeatureAllowlistEntrySchema = FeatureAllowlistEntrySchema;
 exports.FeedActorSchema = FeedActorSchema;
@@ -2791,6 +2888,8 @@ exports.didSchema = didSchema;
 exports.dimensionsFromInputs = dimensionsFromInputs;
 exports.durationFromMinutes = durationFromMinutes;
 exports.encodeFeedCursor = encodeFeedCursor;
+exports.entityDisambiguationLabel = entityDisambiguationLabel;
+exports.entityResultKey = entityResultKey;
 exports.externalRecordRefSchema = externalRecordRefSchema;
 exports.findIndustry = findIndustry;
 exports.formatDistanceToNow = formatDistanceToNow;
@@ -2827,6 +2926,7 @@ exports.isAppCategory = isAppCategory;
 exports.isCompanyRequired = isCompanyRequired;
 exports.isKnownAppId = isKnownAppId;
 exports.isKnownPlatform = isKnownPlatform;
+exports.isPseudoEmployer = isPseudoEmployer;
 exports.isValidRgbColor = isValidRgbColor;
 exports.isVisibleActivityItem = isVisibleActivityItem;
 exports.languageTagSchema = languageTagSchema;
@@ -2856,6 +2956,7 @@ exports.resolveCardUrl = resolveCardUrl;
 exports.rgbToString = rgbToString;
 exports.sanitizeDisplayText = sanitizeDisplayText;
 exports.sanitizeHandleInput = sanitizeHandleInput;
+exports.searchResultDisambiguation = searchResultDisambiguation;
 exports.selfLabelsSchema = selfLabelsSchema;
 exports.singleDateExtractor = singleDateExtractor;
 exports.sortByDateDesc = sortByDateDesc;