@jwilleke/ngdpbase-types 5.29.0 → 5.29.1

package/lib/packages/ngdpbase-types/index.d.ts

@@ -42,6 +42,6 @@ export type { User, UserPreferences } from '../../src/types/User.js';
 export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
 export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';
-export type { Organization, OrganizationInput, OrganizationUpdate } from '../../src/types/Organization.js';
+export type { Organization, OrganizationInput, OrganizationUpdate, ContactPoint, ContactPointEntry, PostalAddress } from '../../src/types/Organization.js';
 export type { ContactRefusedError } from '../../src/utils/contactAccess.js';
 export type { default as RoleManager } from '../../src/managers/RoleManager.js';

package/lib/src/managers/UserManager.d.ts

@@ -517,6 +517,11 @@ declare class UserManager extends BaseManager {
     /**
      * Search users by username, displayName, or email (case-insensitive substring).
      * Optionally filter by role and active status.
+     *
+     * Decides `search-user` itself, with `ctx` (#2018): every user holds it as
+     * shipped, anonymous does not. A refusal throws `ContactRefusedError`. Core's
+     * own lookups (a notice's recipients, a role's holders) pass the system
+     * context with a reason, allowed without a policy evaluation.
      */
     searchUsers(query: string, options: {
         role?: string;

package/lib/src/types/Organization.d.ts

@@ -12,11 +12,15 @@
  * @see https://schema.org/Organization
  */
 /**
- * Schema.org PostalAddress (subset used by Organization)
+ * Schema.org PostalAddress (subset used by Organization/Person).
+ *
+ * In schema.org a PostalAddress is a ContactPoint, so it carries the
+ * ContactPoint fields too: a `contactPoint[]` entry may be one (a mailing or
+ * business address, with its `contactType`, `name` and `telephone`).
  *
  * @see https://schema.org/PostalAddress
  */
-export interface PostalAddress {
+export interface PostalAddress extends Omit<ContactPoint, '@type'> {
     '@type': 'PostalAddress';
     streetAddress?: string | null;
     addressLocality?: string | null;
@@ -32,11 +36,19 @@ export interface PostalAddress {
 export interface ContactPoint {
     '@type': 'ContactPoint';
     contactType?: string;
+    /** Who or what this contact point reaches, e.g. an agent's or an emergency contact's name (schema.org Thing.name). */
+    name?: string;
     email?: string;
     telephone?: string;
     url?: string;
     availableLanguage?: string[];
 }
+/**
+ * One `contactPoint[]` entry: a ContactPoint, or a PostalAddress (schema.org's
+ * ContactPoint subtype). Typed by `contactType` (`mailing`, `business`,
+ * `agent`, `emergency`, …); the home address stays in `address`.
+ */
+export type ContactPointEntry = ContactPoint | PostalAddress;
 /**
  * Canonical Organization record.
  *
@@ -62,8 +74,8 @@ export interface Organization {
     foundingDate?: string;
     /** Postal address */
     address?: PostalAddress;
-    /** Contact points (support, sales, etc.) */
-    contactPoint?: ContactPoint[];
+    /** Contact points (support, sales, a mailing address, etc.) */
+    contactPoint?: ContactPointEntry[];
     /** Other URLs that identify this org (LinkedIn, Twitter, etc.) */
     sameAs?: string[];
     /** Optional legacy slug or external identifier */

package/lib/src/types/Person.d.ts

@@ -15,7 +15,7 @@
  *
  * @see https://schema.org/Person
  */
-import type { PostalAddress, ContactPoint } from './Organization.js';
+import type { PostalAddress, ContactPointEntry } from './Organization.js';
 /**
  * One organization a person is affiliated with (#1930): schema.org
  * `affiliation`, with the person's role or title there when one is known.
@@ -51,8 +51,8 @@ export interface Person {
     email?: string;
     /** Postal address */
     address?: PostalAddress;
-    /** Contact points (work phone, mobile, etc.) */
-    contactPoint?: ContactPoint[];
+    /** Everything but the home address: phones, a mailing or business address (a PostalAddress), an agent, an emergency contact; each typed by `contactType`. */
+    contactPoint?: ContactPointEntry[];
     /** ISO language tags this person knows */
     knowsLanguage?: string[];
     /** Profile/avatar image URL */

package/lib/src/utils/contactAccess.d.ts

@@ -67,6 +67,13 @@ export declare function isSystemWork(engine: EngineLike, ctx: ActorContext | nul
 export declare function requireRecordAccess(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, record?: {
     identifier?: unknown;
 } | null): Promise<void>;
+/**
+ * A lookup of users (#2018): `UserManager.searchUsers` asks `permission`
+ * (`search-user`) with the caller's context, and throws
+ * {@link ContactRefusedError} on a refusal. Core's own work
+ * ({@link isSystemWork}) is allowed without a policy evaluation.
+ */
+export declare function requireLookupPermission(engine: EngineLike, ctx: ActorContext, permission: CorePermission): Promise<void>;
 /** What a contacts record says was done. Names fields, never their values. */
 export interface ContactChange {
     kind: 'person' | 'organization';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.29.0",
+  "version": "5.29.1",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",