@better-giving/endowment 2.0.6 → 3.0.0

package/src/db.mts

@@ -1,151 +1,441 @@
-import type { Ensure } from "@better-giving/types/utils";
+import {
+  DeleteCommand,
+  GetCommand,
+  PutCommand,
+  QueryCommand,
+  TransactWriteCommand,
+  UpdateCommand,
+} from "@aws-sdk/lib-dynamodb";
+import { Db, Txs, UpdateBuilder } from "@better-giving/db";
+import KSUID from "ksuid";
 import type {
-  Endowment as EndowmentShape,
-  Environment,
-  MediaId,
-  MediaType,
-  MilestoneId,
-  Milestone as MilestoneShape,
-  ProgramId,
-  Program as ProgramShape,
-} from "./schema.mjs";
-export type {
-  SocialMediaURLs,
-  Allocation,
-  Increment,
-  EndowDesignation,
-  Environment,
-  ProgramId,
+  IMedia,
+  IMediaDb,
+  IMediaPage,
+  INpoReferredBy,
+  INpoWithRegNum,
+  INpoWithRid,
+  TBinFlag,
+  TNpoDbKeys,
+  TNpoDbProjectedTo,
+} from "./interfaces.mjs";
+import { med_key_filter, med_sk, to_imedia } from "./media.mjs";
+import { projection } from "./npo.mjs";
+import type {
+  IMediaSearchObj,
+  IMilestone,
+  IMilestoneUpdate,
+  INpo,
+  INpoUpdate,
+  IProgram,
+  IProgramDb,
+  IProgramNew,
+  IProgramUpdate,
+  TMediaType,
 } from "./schema.mjs";
 
-export const endowGsi = {
-  regnumEnv: "regnum-env-gsi",
-  slugEnv: "slug-env-gsi",
-} as const;
+export class NpoDb extends Db {
+  static override readonly name = "endowments_v3";
+  static readonly slug_env_gsi = "slug-env-gsi" as const;
+  static readonly regnum_env_gsi = "regnum-env-gsi" as const;
+  key_npo(id: number) {
+    return {
+      PK: `Endow#${id}`,
+      SK: this.env,
+    };
+  }
+  get key_count() {
+    return {
+      PK: "Count",
+      SK: this.env,
+    };
+  }
+  key_npo_program(id: string, npo: number) {
+    return {
+      PK: `Endow#${npo}#${this.env}`,
+      SK: `Prog#${id}`,
+    };
+  }
 
-export namespace EndowCount {
-  export interface Keys {
-    PK: "Count";
-    SK: Environment;
+  key_prog_milestone(id: string, prog: string) {
+    return {
+      PK: `Prog#${prog}#${this.env}`,
+      SK: `Mile#${id}`,
+    };
   }
-  export interface NonKeyAttributes {
-    count: number;
+
+  key_npo_med(ksuid: string, npo: number) {
+    return {
+      PK: `Endow#${npo}#${this.env}`,
+      SK: `Media#${ksuid}`,
+    };
   }
-}
 
-export namespace Endow {
-  export type Keys = {
-    PK: `Endow#${number}`;
-    SK: Environment;
-  };
-
-  export type NonKeyAttributes = EndowmentShape & {
-    /** referral id */
-    gsi1PK?: `ReferredBy#${string}`;
-    /** expiry / date onboarded */
-    gsi1SK?: string;
-    /** Rid#referral_id */
-    gsi2PK?: `Rid#${string}`;
-    gsi2SK?: `Rid#${string}`;
-
-    /** will only be present for unclaimed NPOs */
-    updated_at_auto?: string;
-    /** in USD @deprecated */
-    payout_minimum?: number;
-    /** @deprecated */
-    splitLiqPct?: number;
-    /** @deprecated */
-    splitFixed?: boolean;
-    /** @deprecated */
-    sfCompounded?: boolean;
-  };
-
-  export interface DbRecord extends Keys, NonKeyAttributes {}
-}
+  gsi1_npo(id: string) {
+    return {
+      gsi1PK: `ReferredBy#${id}`,
+      gsi1SK: this.env,
+    };
+  }
 
-export namespace RegNumEnvGsi {
-  export type Name = typeof endowGsi.regnumEnv;
-  export interface Keys
-    extends Pick<Endow.NonKeyAttributes, "registration_number" | "env"> {}
-  export interface DbRecord
-    extends Keys,
-      Endow.Keys,
-      Pick<Endow.NonKeyAttributes, "claimed" | "name" | "hq_country" | "id"> {}
-}
+  gsi2_npo(id: string) {
+    return {
+      gsi2PK: `Rid#${id}`,
+      gsi2SK: `Rid#${id}`,
+    };
+  }
 
-export namespace SlugEnvGsi {
-  export type Name = typeof endowGsi.slugEnv;
-  export interface Keys extends Pick<Endow.NonKeyAttributes, "slug" | "env"> {}
-  export interface DbRecord extends Endow.DbRecord {} //all attributes are copied to this index
-}
+  gsi1_npo_med(id: string, npo: number, featured: TBinFlag, type: TMediaType) {
+    return {
+      gsi1PK: this.key_npo_med(id, npo).PK,
+      gsi1SK: med_sk(id, type, featured),
+    };
+  }
+  async npo_media(npo: number, opts: IMediaSearchObj): Promise<IMediaPage> {
+    const PK: string = this.key_npo_med("ksuid-sk", npo).PK;
+    const [expression, values] = med_key_filter(PK, opts);
+
+    const cmd = new QueryCommand({
+      TableName: NpoDb.name,
+      IndexName: "gsi1",
+      Limit: opts.limit,
+      KeyConditionExpression: expression,
+      ExpressionAttributeValues: values,
+      ExclusiveStartKey: this.key_to_obj(opts.next),
+    });
 
-export namespace Program {
-  export interface Keys {
-    PK: `Endow#${number}#${Environment}`;
-    SK: `Prog#${ProgramId}`;
+    const res = await this.client.send(cmd);
+    const page = this.to_page(res, to_imedia);
+    return page;
   }
 
-  export interface NonKeyAttributes extends ProgramShape {}
-  export interface DbRecord extends Keys, NonKeyAttributes {}
-}
+  async npo_referred_by(id: string): Promise<INpoReferredBy[]> {
+    const cmd = new QueryCommand({
+      TableName: NpoDb.name,
+      IndexName: "gsi1",
+      KeyConditionExpression: "#pk = :pk",
+      ExpressionAttributeValues: {
+        ":pk": this.gsi1_npo(id).gsi1PK,
+      },
+      ExpressionAttributeNames: { "#pk": "gsi1PK" },
+    });
+    const { Items = [] } = await this.client.send(cmd);
+    return Items.map((x) => this.sans_keys(x));
+  }
 
-export namespace Milestone {
-  export interface Keys {
-    PK: `Prog#${string}#${Environment}`;
-    SK: `Mile#${MilestoneId}`;
+  async npo_with_rid(id: string): Promise<INpoWithRid | undefined> {
+    const cmd = new QueryCommand({
+      TableName: NpoDb.name,
+      IndexName: "gsi2",
+      KeyConditionExpression: "gsi2PK = :pk",
+      ExpressionAttributeValues: {
+        ":pk": this.gsi2_npo(id).gsi2PK,
+      },
+      Limit: 1,
+    });
+    const { Items = [] } = await this.client.send(cmd);
+    const i = Items[0];
+    return i && this.sans_keys(i);
   }
-  export interface DbRecord extends Keys, MilestoneShape {}
-}
 
-export namespace Media {
-  export interface Keys {
-    PK: `Endow#${number}#${Environment}`;
-    SK: `Media#${MediaId}`;
+  async npo_with_regnum(
+    regnum: string,
+    country = "United States"
+  ): Promise<INpoWithRegNum | undefined> {
+    const cmd = new QueryCommand({
+      TableName: NpoDb.name,
+      IndexName: NpoDb.regnum_env_gsi,
+      Limit: 1,
+      KeyConditionExpression: "#rn = :rn AND #env = :env",
+
+      FilterExpression: "#country = :country",
+      ExpressionAttributeNames: {
+        "#rn": "registration_number" satisfies TNpoDbKeys,
+        "#env": "env" satisfies TNpoDbKeys,
+        "#country": "hq_country" satisfies TNpoDbKeys,
+      },
+      ExpressionAttributeValues: {
+        ":rn": regnum,
+        ":env": this.env,
+        ":country": country,
+      },
+    });
+
+    const { Items = [] } = await this.client.send(cmd);
+    const i = Items[0];
+    return i && this.sans_keys(i);
   }
 
-  /** "0" - featured (goes before 1), "1" - not-featured */
-  export type FeaturedFlag = "0" | "1";
-  export interface NonKeyAttributes {
-    id: MediaId;
-    gsi1PK: Keys["PK"];
-    gsi1SK: `MediaList#${FeaturedFlag}#${MediaId}#${MediaType}`;
-    /** iso string */
-    dateCreated: string;
+  npo_record(data: INpo) {
+    return {
+      ...this.key_npo(data.id),
+      ...data,
+      ...(data.referrer ? this.gsi1_npo(data.referrer) : {}),
+      ...(data.referral_id ? this.gsi2_npo(data.referral_id) : {}),
+    };
   }
 
-  export interface VideoAttributes extends NonKeyAttributes {
-    type: Extract<MediaType, "video">;
-    url: string;
+  npo_prog_record(npo: number, data: IProgramDb) {
+    return {
+      ...this.key_npo_program(data.id, npo),
+      ...data,
+    };
   }
 
-  export interface VideoDbRecord extends Keys, VideoAttributes {}
-  export type DbRecord = VideoDbRecord; // | album | article
-}
+  prog_milestone_record(prog: string, data: IMilestone) {
+    return {
+      ...this.key_prog_milestone(data.id, prog),
+      ...data,
+    };
+  }
 
-export namespace Gsi1 {
-  export namespace MediaList {
-    export interface Keys
-      extends Pick<Media.NonKeyAttributes, "gsi1PK" | "gsi1SK"> {}
-    export interface DbRecord extends Media.DbRecord {}
+  npo_med_record(
+    npo_id: number,
+    { featured /** not saved as attribute  */, ...d }: IMedia
+  ) {
+    return {
+      ...this.key_npo_med(d.id, npo_id),
+      ...this.gsi1_npo_med(d.id, npo_id, featured ? "1" : "0", d.type),
+      ...(d satisfies IMediaDb),
+    };
   }
 
-  export namespace ReferredNpos {
-    export interface Keys
-      extends Required<Pick<Endow.NonKeyAttributes, "gsi1PK" | "gsi1SK">> {}
-    export interface DbRecord
-      extends Ensure<
-        Endow.DbRecord,
-        "gsi1PK" | "gsi1SK" | "referrer" | "referrer_expiry"
-      > {}
+  async npo_med_put(npo: number, url: string) {
+    const ksuid = KSUID.randomSync();
+    const mid = ksuid.string;
+    const item = this.npo_med_record(npo, {
+      id: mid,
+      url,
+      type: "video",
+      dateCreated: ksuid.date.toISOString(),
+      featured: false,
+    });
+    const command = new PutCommand({
+      TableName: NpoDb.name,
+      Item: item,
+    });
+    await this.client.send(command);
+    return mid;
   }
-}
-export namespace Gsi2 {
-  export namespace Rid {
-    export interface Keys
-      extends Required<Pick<Endow.NonKeyAttributes, "gsi1PK" | "gsi1SK">> {}
-    export interface DbRecord
-      extends Ensure<Endow.DbRecord, "gsi1PK" | "gsi1SK" | "referral_id"> {}
+
+  async npo_med(npo: number, mid: string): Promise<IMedia | undefined> {
+    const cmd = new GetCommand({
+      TableName: NpoDb.name,
+      Key: this.key_npo_med(mid, npo),
+    });
+    const { Item: i } = await this.client.send(cmd);
+    return i && to_imedia(i);
   }
-}
 
-export type DbRecord = Endow.DbRecord | Program.DbRecord;
+  async npo_med_delete(npo: number, mid: string) {
+    const cmd = new DeleteCommand({
+      TableName: NpoDb.name,
+      Key: this.key_npo_med(mid, npo),
+    });
+    return this.client.send(cmd);
+  }
+
+  async npo<T extends TNpoDbKeys[]>(
+    id: string | number,
+    fields?: T
+  ): Promise<TNpoDbProjectedTo<T> | undefined> {
+    const { names, expression } = projection(fields);
+
+    if (typeof id === "string") {
+      const cmd = new QueryCommand({
+        TableName: NpoDb.name,
+        IndexName: NpoDb.slug_env_gsi,
+        KeyConditionExpression: "#slug = :slug and #env = :env",
+        ExpressionAttributeValues: {
+          ":slug": id,
+          ":env": this.env,
+        },
+        ProjectionExpression: expression,
+        ExpressionAttributeNames: {
+          ...names,
+          "#env": "env",
+          "#slug": "slug",
+        },
+      });
+      const [x] = await this.client.send(cmd).then(({ Items: x = [] }) => x);
+      return x ? this.sans_keys(x) : undefined;
+    }
+
+    const cmd = new GetCommand({
+      TableName: NpoDb.name,
+      Key: this.key_npo(id),
+      ProjectionExpression: expression,
+      ExpressionAttributeNames: names,
+    });
+    const { Item: i } = await this.client.send(cmd);
+    return i ? this.sans_keys(i) : undefined;
+  }
+
+  async npo_update(
+    id: number,
+    { target, slug, social_media_urls, ...update }: INpoUpdate
+  ) {
+    const updates = new UpdateBuilder();
+
+    if (slug) updates.set("slug", slug);
+    if (slug === "") updates.remove("slug");
+
+    if (target || target === "0") {
+      updates.set("target", target);
+    }
+
+    if (social_media_urls) {
+      for (const [k, v] of Object.entries(social_media_urls)) {
+        if (v === undefined) continue;
+        updates.set(`social_media_urls.${k}`, v);
+      }
+    }
+
+    for (const [k, v] of Object.entries(update)) {
+      if (v === undefined) continue;
+      updates.set(k, v);
+    }
+
+    const cmd = new UpdateCommand({
+      TableName: NpoDb.name,
+      Key: this.key_npo(id),
+      ReturnValues: "ALL_NEW",
+      ...updates.collect(),
+    });
+
+    return this.client.send(cmd);
+  }
+  async prog_milestones(id: string): Promise<IMilestone[]> {
+    const command = new QueryCommand({
+      TableName: NpoDb.name,
+      KeyConditionExpression: `PK = :PK`,
+      ExpressionAttributeValues: {
+        ":PK": this.key_prog_milestone("not-used", id).PK,
+      },
+    });
+    return this.client
+      .send(command)
+      .then(({ Items: x = [] }) => x.map((i) => this.sans_keys(i)));
+  }
+  async prog_milestone_delete(pid: string, mid: string) {
+    const cmd = new DeleteCommand({
+      TableName: NpoDb.name,
+      Key: this.key_prog_milestone(mid, pid),
+    });
+    return this.client.send(cmd);
+  }
+  async prog_milestone_update(
+    pid: string,
+    mid: string,
+    update: IMilestoneUpdate
+  ) {
+    const upd8 = new UpdateBuilder();
+    for (const [key, value] of Object.entries(update)) {
+      upd8.set(key, value);
+    }
+
+    const cmd = new UpdateCommand({
+      TableName: NpoDb.name,
+      Key: this.key_prog_milestone(mid, pid),
+      ...upd8.collect(),
+      ReturnValues: "ALL_NEW",
+    });
+    return this.client.send(cmd).then((res) => res.Attributes);
+  }
+
+  async npo_program(id: string, npo_id: number): Promise<IProgram | undefined> {
+    const cmd = new GetCommand({
+      TableName: NpoDb.name,
+      Key: this.key_npo_program(id, npo_id),
+    });
+    const { Item: p } = await this.client.send(cmd);
+    if (!p) return undefined;
+
+    const milestones = await this.prog_milestones(id);
+
+    return {
+      ...this.sans_keys<IProgramDb>(p),
+      milestones: milestones.toSorted((a, b) => a.date.localeCompare(b.date)),
+    };
+  }
+  async npo_programs(id: number): Promise<IProgramDb[]> {
+    const cmd = new QueryCommand({
+      TableName: NpoDb.name,
+      KeyConditionExpression: `PK = :PK and begins_with(SK, :SK)`,
+      ExpressionAttributeValues: {
+        ":PK": this.key_npo_program("not-used", id).PK,
+        ":SK": "Prog#",
+      },
+    });
+
+    const { Items: x = [] } = await this.client.send(cmd);
+    return x.map((i) => this.sans_keys(i));
+  }
+
+  async npo_program_put(npo: number, content: IProgramNew): Promise<string> {
+    const pid = crypto.randomUUID();
+
+    const { milestones, ...prog } = content;
+    const txs = new Txs();
+    const db_prog = this.npo_prog_record(npo, {
+      ...prog,
+      id: pid,
+      totalDonations: 0,
+    });
+    txs.put({
+      TableName: NpoDb.name,
+      Item: db_prog,
+    });
+
+    for (const m of milestones || []) {
+      const mid = crypto.randomUUID();
+      txs.put({
+        TableName: NpoDb.name,
+        Item: this.prog_milestone_record(pid, { ...m, id: mid }),
+      });
+    }
+
+    const cmd = new TransactWriteCommand({
+      TransactItems: txs.all,
+    });
+
+    await this.client.send(cmd);
+    return pid;
+  }
+
+  async npo_prog_del(npo: number, prog: string) {
+    const milestones = await this.prog_milestones(prog);
+    const txs = new Txs();
+    txs.del({
+      TableName: NpoDb.name,
+      Key: this.key_npo_program(prog, npo),
+    });
+
+    for (const m of milestones) {
+      txs.del({
+        TableName: NpoDb.name,
+        Key: this.key_prog_milestone(m.id, prog),
+      });
+    }
+
+    const cmd = new TransactWriteCommand({
+      TransactItems: txs.all,
+    });
+    return this.client.send(cmd);
+  }
+
+  async npo_prog_update(npo: number, prog: string, update: IProgramUpdate) {
+    const upd8 = new UpdateBuilder();
+    for (const [key, value] of Object.entries(update)) {
+      upd8.set(key, value);
+    }
+
+    const cmd = new UpdateCommand({
+      TableName: NpoDb.name,
+      Key: this.key_npo_program(prog, npo),
+      ...upd8.collect(),
+      ReturnValues: "ALL_NEW",
+    });
+    return this.client.send(cmd).then((res) => res.Attributes);
+  }
+}

package/src/index.mts

@@ -1,50 +1,7 @@
-import type { IPageKeyed } from "@better-giving/types/api";
-import type { CloudsearchEndow as EndowItem } from "./cloudsearch.mjs";
-import type { Media } from "./db.mjs";
-import type { Milestone, Program as ProgramShape } from "./schema.mjs";
-export type {
-  Allocation,
-  DonateMethodId,
-  EndowDesignation,
-  Endowment as Endow,
-  EndowFields,
-  EndowQueryParams,
-  EndowUpdate,
-  Environment,
-  Increment,
-  MediaQueryParams,
-  MediaQueryParamsObj,
-  MediaType,
-  MediaUpdate,
-  Milestone,
-  MilestoneUpdate,
-  NewMilestone,
-  NewProgram,
-  ProgramUpdate,
-  SocialMediaURLs,
-  UnSdgNum,
-} from "./schema.mjs";
+export * from "./interfaces.mjs";
+export { NpoDb } from "./db.mjs";
 export type {
   CloudsearchEndow as EndowItem,
   CloudsearchEndowsQueryParams as EndowsQueryParams,
   CloudsearchEndowsQueryParamsParsed as EndowsQueryParamsParsed,
 } from "./cloudsearch.mjs";
-
-/** client responsible on T depending on keys projected */
-export interface EndowsPage<T extends keyof EndowItem = keyof EndowItem> {
-  items: Pick<EndowItem, T>[];
-  page: number;
-  pages: number;
-}
-
-export interface Program extends ProgramShape {
-  milestones: Milestone[];
-}
-
-/** web-app format */
-export interface IMedia
-  extends Omit<Media.DbRecord, "PK" | "SK" | "gsi1PK" | "gsi1SK"> {
-  featured: boolean;
-}
-
-export interface MediaPage extends IPageKeyed<IMedia> {}

package/src/interfaces.mts

@@ -0,0 +1,73 @@
+import type { IPageKeyed } from "@better-giving/types/api";
+import type { Ensure } from "@better-giving/types/utils";
+import type { IMediaUpdate, INpo, TMediaType } from "./schema.mjs";
+
+export type {
+  IAllocation,
+  INpo,
+  INpoFields,
+  INposSearch,
+  INpoUpdate,
+  IIncrement,
+  IMediaSearch,
+  IMediaSearchObj,
+  TMediaType,
+  IMediaUpdate,
+  IMilestone,
+  IMilestoneUpdate,
+  IMilestoneNew,
+  IProgramNew,
+  IProgramUpdate,
+  ISocialMediaURLs,
+} from "./schema.mjs";
+
+export {
+  type OrgDesignation as EndowDesignation,
+  type Environment,
+  type UnSdgNum,
+  type DonateMethodId,
+  https_url,
+} from "@better-giving/schemas";
+
+export interface INpoDb extends INpo {
+  /** will only be present for unclaimed NPOs */
+  updated_at_auto?: string;
+  /** in USD @deprecated */
+  payout_minimum?: number;
+  /** @deprecated */
+  splitLiqPct?: number;
+  /** @deprecated */
+  splitFixed?: boolean;
+  /** @deprecated */
+  sfCompounded?: boolean;
+}
+
+export interface INpoReferredBy
+  extends Ensure<INpo, "referrer" | "referrer_expiry"> {}
+
+export interface INpoWithRid extends Ensure<INpo, "referral_id"> {}
+
+export interface INpoWithRegNum
+  extends Pick<INpo, "claimed" | "name" | "hq_country" | "id"> {}
+
+export interface IMedia extends Required<IMediaUpdate> {
+  id: string;
+  type: Extract<TMediaType, "video">; // only video for now
+  dateCreated: string;
+}
+export interface IMediaDb extends Omit<IMedia, "featured"> {}
+export interface IMediaPage extends IPageKeyed<IMedia> {}
+
+export type TNpoDbKeys = keyof INpoDb;
+export type TArrayValues<T extends readonly unknown[]> = T[number];
+export type TNpoDbProjectedTo<T> = T extends TNpoDbKeys[]
+  ? Pick<INpoDb, TArrayValues<T>>
+  : INpoDb;
+
+export type TBinFlag = "0" | "1";
+
+export interface INposPage<T extends keyof INpoDb = keyof INpoDb> {
+  items: Pick<INpoDb, T>[];
+  page: number;
+  pages: number;
+}