@awesomate/sdk 0.51.0 → 0.52.0

package/dist/index.d.ts

@@ -26,7 +26,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export declare const VERSION = "0.51.0";
+export declare const VERSION = "0.52.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -1349,6 +1349,21 @@ export declare class AwesomateClient {
      * const { id, created } = await db.upsertByRef('job', { system: 'servicem8', externalId: 'JOB-0042' }, { title: 'Possum in the roof' }, { links: { customer: contactId } });
      */
     upsertByRef<K extends KindName>(kind: K, ref: RecordRef, data?: Partial<RowOf<K>> | Record<string, unknown>, options?: Omit<WriteOptions, 'id'>): Promise<UpsertByRefResult>;
+    /**
+     * The record that mirrors one in another system, read back by that system's name and its id there
+     * (the same `ref` upsertByRef() keys on), so a sync can ask "do I have Xero invoice INV-0042?"
+     * without keeping our ids. Answers the row exactly as get() reads it (fields readable by AI only),
+     * or null when this kind has no record with that id. A record with that id that was archived throws
+     * `conflict` (as upsertByRef() does): a sync leaves it alone rather than making another. Contacts and
+     * companies have no outside ids. The account's token only (never an app key), crm:read, every plan.
+     *
+     * @example
+     * const job = await db.getByRef('job', { system: 'servicem8', externalId: 'JOB-0042' });
+     * if (!job) await db.upsertByRef('job', { system: 'servicem8', externalId: 'JOB-0042' }, { title: 'Possum in the roof' });
+     */
+    getByRef<K extends KindName>(kind: K, ref: RecordRef, options?: {
+        tz?: string;
+    }): Promise<RowOf<K> | null>;
     /** The saved queries on this account. crm:read, every plan: the account's token or an app key. */
     queries(): Promise<SavedQueryDescription[]>;
     /**
@@ -2357,7 +2372,7 @@ export interface WriteOptions {
     /** Set a link by its key ('<id>'), or end it (null). */
     links?: Record<string, string | null>;
 }
-/** Which record in another system a record mirrors, for upsertByRef(). */
+/** Which record in another system a record mirrors, for upsertByRef() and getByRef(). */
 export interface RecordRef {
     /** That system's name, lower case: letters, digits, `_`, `.` or `-`, at most 40 characters (`xero`, `shopify`). */
     system: string;

package/dist/index.js

@@ -26,7 +26,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.51.0';
+export const VERSION = '0.52.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 /** Every record and contact id is a UUID; anything else can name no row. */
 const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -1181,6 +1181,27 @@ export class AwesomateClient {
         }, false);
         return r.result;
     }
+    /**
+     * The record that mirrors one in another system, read back by that system's name and its id there
+     * (the same `ref` upsertByRef() keys on), so a sync can ask "do I have Xero invoice INV-0042?"
+     * without keeping our ids. Answers the row exactly as get() reads it (fields readable by AI only),
+     * or null when this kind has no record with that id. A record with that id that was archived throws
+     * `conflict` (as upsertByRef() does): a sync leaves it alone rather than making another. Contacts and
+     * companies have no outside ids. The account's token only (never an app key), crm:read, every plan.
+     *
+     * @example
+     * const job = await db.getByRef('job', { system: 'servicem8', externalId: 'JOB-0042' });
+     * if (!job) await db.upsertByRef('job', { system: 'servicem8', externalId: 'JOB-0042' }, { title: 'Possum in the roof' });
+     */
+    async getByRef(kind, ref, options = {}) {
+        if (this.appKey)
+            throw new AwesomateError('forbidden', "getByRef needs the account's token (amt_pat_...). An app key reads records with get() and query().", 0);
+        const qs = new URLSearchParams({ system: ref.system, external_id: ref.externalId });
+        if (options.tz)
+            qs.set('tz', options.tz);
+        const r = await nullIfMissing(this.request('GET', `/api/my-crm/v1/records/${encodeURIComponent(kind)}/by-ref?${qs}`));
+        return r ? r.row : null;
+    }
     /** The saved queries on this account. crm:read, every plan: the account's token or an app key. */
     async queries() {
         return (await this.request('GET', '/api/my-crm/v1/queries')).queries;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Your own Awesomate data from Node and the browser: query contacts and app data with generated types, and sign your app's own users in",
   "license": "MIT",
   "type": "module",