@hasna/contacts 0.7.0 → 0.8.1

package/dist/generated/storage-kit/own.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"own.d.ts","sourceRoot":"","sources":["../../../src/generated/storage-kit/own.ts"],"names":[],"mappings":"AAyCA;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAMtE;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1E"}

package/dist/generated/storage-kit/pool.d.ts

@@ -1,15 +1,6 @@
 import type { Pool } from "pg";
 import { type TlsResolveOptions } from "./tls.js";
 import { type PoolQueryClient } from "./query.js";
-type KitEnv = Record<string, string | undefined>;
-/** Throw when a retired storage-mode variable is set for an app. Safe to call
- * from any server backend resolver: a no-op when no legacy key is set. */
-export declare function assertNoRetiredStorageMode(appName: string, env?: KitEnv): void;
-/** Resolve the Postgres DSN from the standard env aliases, never logging it. */
-export declare function resolveDatabaseUrl(appName: string, env?: KitEnv): {
-    value: string | null;
-    source: string | null;
-};
 export interface CreatePgPoolOptions extends TlsResolveOptions {
     connectionString: string;
     /** Max clients in the pool. Defaults to pg's default (10). */
@@ -23,22 +14,19 @@ export interface CreatePgPoolOptions extends TlsResolveOptions {
 }
 /** Build a `pg.Pool` with fleet-standard TLS handling. */
 export declare function createPgPool(options: CreatePgPoolOptions): Pool;
-export interface CreateCloudPoolFromEnvOptions extends TlsResolveOptions {
+export interface CreateServerPoolFromEnvOptions extends TlsResolveOptions {
     max?: number;
     idleTimeoutMillis?: number;
     connectionTimeoutMillis?: number;
     applicationName?: string;
 }
-export interface CloudPoolFromEnv {
+export interface ServerPoolFromEnv {
     client: PoolQueryClient;
     connectionSource: string;
 }
 /**
- * Resolve the database URL from the environment and build a cloud pool.
- *
- * Throws when a retired storage-mode variable is set (deployment modes no
- * longer exist) or when the database URL is missing. Never logs the URL.
+ * Resolve the required database URL and build the server's PostgreSQL pool.
+ * Missing or invalid configuration throws without logging the URL.
  */
-export declare function createCloudPoolFromEnv(appName: string, options?: CreateCloudPoolFromEnvOptions): CloudPoolFromEnv;
-export {};
+export declare function createServerPoolFromEnv(appName: string, options?: CreateServerPoolFromEnvOptions): ServerPoolFromEnv;
 //# sourceMappingURL=pool.d.ts.map

package/dist/generated/storage-kit/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../../src/generated/storage-kit/pool.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,IAAI,CAAC;AAC3C,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAErE,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AASjD;0EAC0E;AAC1E,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAoB,GAAG,IAAI,CAY3F;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAoB,GAAG;IAC9E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAOA;AAED,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAe/D;AAED,MAAM,WAAW,6BAA8B,SAAQ,iBAAiB;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB,CA0BlB"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../../src/generated/storage-kit/pool.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,IAAI,CAAC;AAE3C,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAgDrE,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAmC/D;AAED,MAAM,WAAW,8BAA+B,SAAQ,iBAAiB;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,8BAAmC,GAC3C,iBAAiB,CAcnB"}

package/dist/generated/storage-kit/query.d.ts

@@ -17,7 +17,7 @@ export interface PgExecutor {
 export interface TypedQueryClient {
     query<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<QueryResult<T>>;
     many<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T[]>;
-    /** First row or `null`. Restored here after open-knowledge dropped it. */
+    /** First row or `null`. Restored here after knowledge dropped it. */
     get<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T | null>;
     /** Exactly one row; throws if zero or more than one row is returned. */
     one<T extends QueryResultRow>(sql: string, params?: readonly unknown[]): Promise<T>;

package/dist/generated/storage-kit/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/generated/storage-kit/query.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,IAAI,EAAc,cAAc,EAAE,MAAM,IAAI,CAAC;AAE3D,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,cAAc;IACnD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,CAAC,SAAS,cAAc,EAC5B,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAC1B,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACnG,IAAI,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACvF,0EAA0E;IAC1E,GAAG,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3F,wEAAwE;IACxE,GAAG,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,GAAG,gBAAgB,CAyBnE;AAED,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,kFAAkF;IAClF,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,eAAe,CA2B7D"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/generated/storage-kit/query.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,IAAI,EAAc,cAAc,EAAE,MAAM,IAAI,CAAC;AAE3D,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,cAAc;IACnD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,CAAC,SAAS,cAAc,EAC5B,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAC1B,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACnG,IAAI,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACvF,qEAAqE;IACrE,GAAG,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3F,wEAAwE;IACxE,GAAG,CAAC,CAAC,SAAS,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,GAAG,gBAAgB,CAyBnE;AAED,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,kFAAkF;IAClF,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,eAAe,CA2B7D"}

package/dist/generated/storage-kit/tls.d.ts

@@ -2,6 +2,9 @@
 export type PgSslConfig = boolean | {
     rejectUnauthorized: boolean;
     ca?: string;
+    cert?: string;
+    key?: string;
+    passphrase?: string;
 };
 export interface TlsResolveOptions {
     /** Inline CA bundle (PEM). Wins over every other CA source. */
@@ -12,15 +15,39 @@ export interface TlsResolveOptions {
     env?: Record<string, string | undefined>;
 }
 export type SslMode = "disable" | "prefer" | "require" | "verify-ca" | "verify-full";
+/**
+ * Remove the TLS query parameters once this module has resolved them into an
+ * explicit `ssl` option. pg re-parses `connectionString` AFTER merging pool
+ * options and lets the parse win, so leaving `sslmode` (or `ssl`, `sslcert`,
+ * `sslkey`, `sslrootcert`, `sslnegotiation`) in the URL replaces the resolved
+ * SSL object with pg's own — discarding the CA bundle with it.
+ *
+ * Non-TLS parameters and any fragment are preserved exactly.
+ */
+export declare function connectionStringWithoutTlsParameters(connectionString: string): string;
+/**
+ * Preserve pg's transport negotiation choice outside the stripped URL, so
+ * `sslnegotiation=direct` survives as an explicit pool option instead of being
+ * silently dropped.
+ */
+export declare function sslNegotiationFromConnectionString(connectionString: string): "postgres" | "direct" | undefined;
 /**
  * Extract the effective `sslmode` from a Postgres connection string. Honors the
- * `sslmode` query param and the legacy `ssl=true` boolean. Returns `disable`
- * when TLS is not requested.
+ * `sslmode` query param, the legacy `ssl=true` boolean, and pg's rule that
+ * `sslnegotiation=direct` implies TLS when no explicit SSL setting is present.
+ * Returns `disable` when TLS is not requested.
  */
 export declare function sslModeFromConnectionString(connectionString: string): SslMode;
 /**
  * Resolve the `pg` ssl config for a connection string. See the module header
- * for the full mode table. Returns `undefined` when TLS should be off.
+ * for the full mode table.
+ *
+ * Returns `false` when TLS was explicitly switched off, and `undefined` when the
+ * DSN expressed no TLS policy at all — those are different answers, and pg
+ * treats them differently: only `undefined` lets `PGSSLMODE` decide.
+ *
+ * The caller MUST hand pg `connectionStringWithoutTlsParameters(connectionString)`
+ * rather than the original DSN, or pg discards everything resolved here.
  */
 export declare function resolveTlsConfig(connectionString: string, options?: TlsResolveOptions): PgSslConfig | undefined;
 //# sourceMappingURL=tls.d.ts.map

package/dist/generated/storage-kit/tls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tls.d.ts","sourceRoot":"","sources":["../../../src/generated/storage-kit/tls.ts"],"names":[],"mappings":"AAkCA,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG;IAAE,kBAAkB,EAAE,OAAO,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;AAErF;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAwB7E;AAUD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,iBAAsB,GAC9B,WAAW,GAAG,SAAS,CA2BzB"}
+{"version":3,"file":"tls.d.ts","sourceRoot":"","sources":["../../../src/generated/storage-kit/tls.ts"],"names":[],"mappings":"AAwNA,iEAAiE;AACjE,MAAM,MAAM,WAAW,GACnB,OAAO,GACP;IACE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;AA+BrF;;;;;;;;GAQG;AACH,wBAAgB,oCAAoC,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAOrF;AAgBD;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,gBAAgB,EAAE,MAAM,GACvB,UAAU,GAAG,QAAQ,GAAG,SAAS,CAKnC;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAmD7E;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,iBAAsB,GAC9B,WAAW,GAAG,SAAS,CAgEzB"}

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { ContactProjectMembershipListResult, ContactProjectMembershipMutati
 export { ContactProjectMembershipConflictError } from "./types/project-memberships.js";
 export type { EmailType, PhoneType, AddressType, SocialPlatform, RelationshipType, ContactSource, PreferredContactMethod, ContactStatus, Sensitivity, EntityType, CompanyRelationshipType, VendorCommType, VendorCommDirection, VendorCommStatus, ApplicationType, ApplicationStatus, ApplicationMethod, DealStage, EventType, Email, Phone, Address, SocialProfile, Tag, Contact, ContactWithDetails, Company, CompanyWithDetails, ContactRelationship, CompanyRelationship, ActivityLog, Webhook, Group, CreateGroupInput, UpdateGroupInput, ContactNote, OrgMember, VendorCommunication, EscalationRule, ContactTask, Application, Deal, ContactEvent, CreateEmailInput, CreatePhoneInput, CreateAddressInput, CreateSocialProfileInput, CreateTagInput, UpdateTagInput, CreateContactInput, UpdateContactInput, ContactListOptions, CreateCompanyInput, UpdateCompanyInput, CompanyListOptions, CreateRelationshipInput, CreateCompanyRelationshipInput, CreateActivityInput, CreateWebhookInput, UpdateWebhookInput, DuplicateByEmail, DuplicateByName, CreateOrgMemberInput, UpdateOrgMemberInput, CreateVendorCommunicationInput, UpdateVendorCommunicationInput, CreateContactTaskInput, UpdateContactTaskInput, CreateApplicationInput, UpdateApplicationInput, ListApplicationsOptions, CreateDealInput, UpdateDealInput, CreateEventInput, AudienceChannel, ConsentStatus, ConsentPolicy, AudienceMatch, AudiencePredicateKind, AudiencePredicateOp, AudiencePredicateValue, AudiencePredicate, Audience, AudienceRow, CreateAudienceInput, UpdateAudienceInput, ContactConsent, ContactSuppression, AudienceRecipient, AudienceExclusion, AudienceResolution, ContactRow, CompanyRow, EmailRow, PhoneRow, AddressRow, SocialProfileRow, TagRow, RelationshipRow, ActivityRow, WebhookRow, } from "./types/index.js";
 export { ContactNotFoundError, CompanyNotFoundError, TagNotFoundError, DuplicateTagNameError, AudienceNotFoundError, DuplicateAudienceIdError, InvalidAudienceDefinitionError, AUDIENCE_CHANNELS, CONSENT_STATUSES, CONSENT_POLICIES, } from "./types/index.js";
-export { ContactsV1Client, ContactsV1ApiError, } from "./sdk/index.js";
-export type { ContactsV1ClientOptions, ContactsV1Contact, ContactsV1Company, ContactsV1Tag, ContactsV1CreateContactInput, ContactsV1UpdateContactInput, ContactsV1CreateCompanyInput, ContactsV1UpdateCompanyInput, ContactsV1CreateTagInput, ContactsV1UpdateTagInput, ContactsV1ProjectMembershipSnapshot, ContactsV1ProjectMembershipMutationInput, ContactsV1ProjectMembershipMutationResult, ContactsV1ProjectMembershipListResult, } from "./sdk/index.js";
+export { ContactsV1Client, ContactsV1ApiError, createContactsClient, contactsSdkAuthorityPinMessage, } from "./sdk/index.js";
+export type { ContactsV1ClientOptions, CreateContactsClientOptions, ContactsV1Contact, ContactsV1Company, ContactsV1Tag, ContactsV1CreateContactInput, ContactsV1UpdateContactInput, ContactsV1CreateCompanyInput, ContactsV1UpdateCompanyInput, ContactsV1CreateTagInput, ContactsV1UpdateTagInput, ContactsV1ProjectMembershipSnapshot, ContactsV1ProjectMembershipMutationInput, ContactsV1ProjectMembershipMutationResult, ContactsV1ProjectMembershipListResult, } from "./sdk/index.js";
 export { buildV1OpenApiDocument } from "./server/openapi.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,kCAAkC,EAClC,yCAAyC,EACzC,qCAAqC,EACrC,sCAAsC,EACtC,gCAAgC,GACjC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,qCAAqC,EAAE,MAAM,gCAAgC,CAAC;AAGvF,YAAY,EAEV,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,UAAU,EACV,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,SAAS,EAET,KAAK,EACL,KAAK,EACL,OAAO,EACP,aAAa,EAEb,GAAG,EACH,OAAO,EACP,kBAAkB,EAClB,OAAO,EACP,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,OAAO,EACP,KAAK,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,WAAW,EACX,IAAI,EACJ,YAAY,EAEZ,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,8BAA8B,EAC9B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,8BAA8B,EAC9B,8BAA8B,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,gBAAgB,EAEhB,eAAe,EACf,aAAa,EACb,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAElB,UAAU,EACV,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,MAAM,EACN,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAEL,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,8BAA8B,EAE9B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACxB,mCAAmC,EACnC,wCAAwC,EACxC,yCAAyC,EACzC,qCAAqC,GACtC,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,kCAAkC,EAClC,yCAAyC,EACzC,qCAAqC,EACrC,sCAAsC,EACtC,gCAAgC,GACjC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,qCAAqC,EAAE,MAAM,gCAAgC,CAAC;AAGvF,YAAY,EAEV,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,UAAU,EACV,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,SAAS,EAET,KAAK,EACL,KAAK,EACL,OAAO,EACP,aAAa,EAEb,GAAG,EACH,OAAO,EACP,kBAAkB,EAClB,OAAO,EACP,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,OAAO,EACP,KAAK,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,WAAW,EACX,IAAI,EACJ,YAAY,EAEZ,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,8BAA8B,EAC9B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,8BAA8B,EAC9B,8BAA8B,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,gBAAgB,EAEhB,eAAe,EACf,aAAa,EACb,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAElB,UAAU,EACV,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,MAAM,EACN,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAEL,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,8BAA8B,EAE9B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,uBAAuB,EACvB,2BAA2B,EAC3B,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACxB,mCAAmC,EACnC,wCAAwC,EACxC,yCAAyC,EACzC,qCAAqC,GACtC,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 // @bun
 // src/cloud/http-storage.ts
 import {
+  ClientTransportConfigurationError,
   createHasnaHttpTransport,
   resolveCredential,
   resolveClientTransport as resolveSharedClientTransport
@@ -90,6 +91,27 @@ function assertConfigurationUnchanged(env, expected) {
     invalid();
 }
 
+// src/cloud/resolver-inputs.ts
+import {
+  clientTransportEnvKeys as clientTransportEnvKeys2,
+  credentialOverrideEnvKey,
+  credentialPointerEnvKey,
+  CREDENTIAL_PROFILE_ENV_KEY
+} from "@hasna/contracts/client";
+var CONTRACTS_AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+function isAmbientContactsEnv(env) {
+  if (typeof process !== "undefined" && env === process.env)
+    return true;
+  return env[CONTRACTS_AMBIENT_ENVIRONMENT] === true;
+}
+function contactsResolverCredentials(env, credentials = {}) {
+  const keychain = { ...credentials.keychain };
+  if (keychain.enabled === undefined && keychain.run === undefined) {
+    keychain.enabled = isAmbientContactsEnv(env);
+  }
+  return { ...credentials, keychain };
+}
+
 // src/cloud/http-storage.ts
 var RETIRED_CLIENT_SELECTOR_KEYS = [
   "HASNA_CONTACTS_STORAGE_MODE",
@@ -125,37 +147,44 @@ class ContactsClientConfigurationError extends Error {
     this.name = "ContactsClientConfigurationError";
   }
 }
-function unconfiguredResolution(resolution, issue) {
+function unconfiguredResolution(issue, resolution, warning = null) {
   return {
     transport: "unconfigured",
     baseUrl: null,
-    apiUrlSource: resolution.apiUrlSource,
-    apiKeyPresent: resolution.apiKeyPresent,
-    apiKeySource: resolution.apiKeySource,
-    apiKeyTier: resolution.apiKeyTier,
+    apiUrlSource: resolution?.apiUrlSource ?? null,
+    apiKeyPresent: resolution?.apiKeyPresent ?? false,
+    apiKeySource: resolution?.apiKeySource ?? null,
+    apiKeyTier: resolution?.apiKeyTier ?? null,
     configured: false,
     misconfigured: true,
     issue,
-    warning: null
+    warning
   };
 }
-function resolveContactsClientTransport(name, env = process.env) {
+function resolveContactsClientTransport(name, env = process.env, credentials = {}) {
   if (name !== "contacts") {
     throw new ContactsClientConfigurationError("CONTACTS_CLIENT_NAME_INVALID", "This resolver only accepts the contacts app slug.");
   }
   assertNoRetiredClientSelectors(env);
   const stamp = clientConfigurationStamp(env);
-  const resolution = resolveSharedClientTransport(name, env);
-  assertConfigurationUnchanged(env, stamp);
-  if (resolution.transport !== "http" || !resolution.baseUrl) {
-    const issue = resolution.misconfigured ? "The configured contacts API URL or credential is invalid or incomplete." : "HASNA_CONTACTS_API_URL and a resolvable contacts API key are required; no local fallback exists.";
-    return unconfiguredResolution(resolution, issue);
+  let resolution;
+  try {
+    resolution = resolveSharedClientTransport(name, env, {
+      credentials: contactsResolverCredentials(env, credentials)
+    });
+  } catch (error) {
+    assertConfigurationUnchanged(env, stamp);
+    if (error instanceof ClientTransportConfigurationError) {
+      return unconfiguredResolution(error.message, null);
+    }
+    throw error;
   }
+  assertConfigurationUnchanged(env, stamp);
   try {
     assertHttpsBaseUrl(resolution.baseUrl);
   } catch (error) {
     return {
-      ...unconfiguredResolution(resolution, error instanceof Error ? error.message : String(error)),
+      ...unconfiguredResolution(error instanceof Error ? error.message : String(error), resolution),
       apiKeyPresent: resolution.apiKeyPresent
     };
   }
@@ -169,7 +198,7 @@ function resolveContactsClientTransport(name, env = process.env) {
     configured: true,
     misconfigured: false,
     issue: null,
-    warning: null
+    warning: resolution.warning
   };
 }
 function resourcePath(resource) {
@@ -223,20 +252,21 @@ function createStorageClient(name, transport) {
     }
   };
 }
-function resolveContactsStorageClient(name, env = process.env) {
-  const resolution = resolveContactsClientTransport(name, env);
+function resolveContactsStorageClient(name, env = process.env, credentials = {}) {
+  const resolution = resolveContactsClientTransport(name, env, credentials);
   if (!resolution.configured || !resolution.baseUrl) {
     throw new ContactsClientConfigurationError("CONTACTS_API_NOT_CONFIGURED", `${resolution.issue ?? "The contacts API client is not configured."} ` + "Configure HASNA_CONTACTS_API_URL and a contacts API key; the client will not read or create a local SQLite database.");
   }
   const baseUrl = resolution.baseUrl;
+  const chainOptions = contactsResolverCredentials(env, credentials);
   const request = async (method, path, body, opts) => {
     const stamp = clientConfigurationStamp(env);
     const snapshot = { ...env };
-    const current = resolveContactsClientTransport(name, snapshot);
+    const current = resolveContactsClientTransport(name, snapshot, chainOptions);
     if (!current.configured || current.baseUrl !== baseUrl) {
       throw new ContactsClientConfigurationError("CONTACTS_AUTHORITY_CHANGED", "Client authority changed or disappeared; construct a new client before sending data.");
     }
-    const credential = resolveCredential(name, snapshot);
+    const credential = resolveCredential(name, snapshot, chainOptions);
     if (!credential)
       throw new ContactsClientConfigurationError("CONTACTS_API_NOT_CONFIGURED", "No credential is available.");
     assertConfigurationUnchanged(env, stamp);
@@ -979,6 +1009,9 @@ class InvalidAudienceDefinitionError extends Error {
     this.name = "InvalidAudienceDefinitionError";
   }
 }
+// src/sdk/index.ts
+import { resolveCredential as resolveCredential2 } from "@hasna/contracts/client";
+
 // src/sdk/v1.generated.ts
 class ApiError extends Error {
   status;
@@ -1239,15 +1272,11 @@ function validateBaseUrl(raw) {
     throw new Error("ContactsV1Client baseUrl must not contain credentials.");
   if (url.search || url.hash)
     throw new Error("ContactsV1Client baseUrl must not contain a query or fragment.");
-  const path = url.pathname.replace(/\/+$/, "");
-  if (path && path !== "/v1") {
-    throw new Error("ContactsV1Client baseUrl must be an authority root or end in /v1.");
-  }
-  url.pathname = "";
+  url.pathname = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "");
   return url.toString().replace(/\/+$/, "");
 }
 function validateApiKey(apiKey) {
-  const key = apiKey.trim();
+  const key = (apiKey ?? "").trim();
   if (!key)
     throw new Error("ContactsV1Client requires an API key.");
   if (/[^\t\x20-\x7e]/.test(key)) {
@@ -1267,6 +1296,56 @@ class ContactsV1Client2 extends ContactsV1Client {
     });
   }
 }
+var CONTACTS_APP_NAME = "contacts";
+function contactsSdkAuthorityPinMessage() {
+  return "an explicit baseUrl requires an explicit apiKey. The SDK never attaches a credential that " + "resolved for a different authority: pass `apiKey` explicitly, or omit `baseUrl` and let the " + "@hasna/contracts chain resolve both halves together.";
+}
+var SDK_HOSTED_ONLY = "The contacts SDK is hosted-only and never falls back to local data.";
+function resolveSdkCredential(env, chainOptions) {
+  const credential = resolveCredential2(CONTACTS_APP_NAME, env, chainOptions);
+  if (!credential) {
+    const diagnosis = resolveContactsClientTransport(CONTACTS_APP_NAME, env, chainOptions);
+    throw new ContactsClientConfigurationError("CONTACTS_API_NOT_CONFIGURED", `${diagnosis.issue ?? "No contacts credential resolved."} ${SDK_HOSTED_ONLY}`);
+  }
+  if (credential.tier === "pointer") {
+    throw new ContactsClientConfigurationError("CONTACTS_CREDENTIAL_POINTER_UNSUPPORTED", `The contacts SDK resolves credentials synchronously and cannot complete the secrets-vault pointer ` + `${credential.source} per request. Use a literal tier instead: an explicit apiKey, the Keychain item ` + `hasna.credentials.${CONTACTS_APP_NAME}.api-key, ~/.hasna/${CONTACTS_APP_NAME}/config/credentials, ` + `or HASNA_CONTACTS_API_KEY.`);
+  }
+  return credential.apiKey;
+}
+function createContactsClient(options = {}) {
+  const { baseUrl, apiKey, env, profile, keychain, ...clientOptions } = options;
+  if (baseUrl !== undefined) {
+    if (!apiKey)
+      throw new ContactsClientConfigurationError("CONTACTS_CREDENTIAL_PINNED", contactsSdkAuthorityPinMessage());
+    return new ContactsV1Client2({ ...clientOptions, baseUrl, apiKey });
+  }
+  const envObject = env ?? (typeof process !== "undefined" ? process.env : {});
+  const requested = {
+    ...apiKey !== undefined ? { apiKey } : {},
+    ...profile !== undefined ? { profile } : {},
+    ...keychain !== undefined ? { keychain } : {}
+  };
+  const chainOptions = contactsResolverCredentials(envObject, requested);
+  const initialKey = resolveSdkCredential(envObject, chainOptions);
+  const resolution = resolveContactsClientTransport(CONTACTS_APP_NAME, envObject, { ...chainOptions, apiKey: initialKey });
+  if (!resolution.configured || !resolution.baseUrl) {
+    throw new ContactsClientConfigurationError("CONTACTS_API_NOT_CONFIGURED", `${resolution.issue ?? "The contacts API client is not configured."} ${SDK_HOSTED_ONLY}`);
+  }
+  const pinnedBaseUrl = resolution.baseUrl;
+  const baseFetch = clientOptions.fetch ?? globalThis.fetch;
+  const chainFetch = async (input, init) => {
+    const snapshot = { ...envObject };
+    const freshKey = resolveSdkCredential(snapshot, chainOptions);
+    const current = resolveContactsClientTransport(CONTACTS_APP_NAME, snapshot, { ...chainOptions, apiKey: freshKey });
+    if (!current.configured || current.baseUrl !== pinnedBaseUrl) {
+      throw new ContactsClientConfigurationError("CONTACTS_AUTHORITY_CHANGED", "Client authority changed or disappeared; construct a new client before sending data.");
+    }
+    const headers = new Headers(init?.headers);
+    headers.set("x-api-key", freshKey);
+    return baseFetch(input, { ...init, headers });
+  };
+  return new ContactsV1Client2({ ...clientOptions, baseUrl: pinnedBaseUrl, apiKey: initialKey, fetch: chainFetch });
+}
 // src/lib/package-version.ts
 import { existsSync, readFileSync as readFileSync2 } from "fs";
 import { dirname, join } from "path";
@@ -1864,6 +1943,8 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
 export {
   resetStoreCache,
   getStore,
+  createContactsClient,
+  contactsSdkAuthorityPinMessage,
   buildV1OpenApiDocument,
   TagNotFoundError,
   InvalidAudienceDefinitionError,

package/dist/mcp/index.d.ts

@@ -1,5 +1,14 @@
 #!/usr/bin/env bun
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function buildServer(): McpServer;
+/**
+ * Classify early-exit arguments before any http-mode parse, server build, or
+ * stdio bind. `--help` / `--version` answer with rc=0 and the MCP server never
+ * starts: previously `contacts-mcp --version` fell through to the stdio
+ * JSON-RPC loop and printed "running on stdio" instead of the version
+ * (hasna/apps#1720 validation, the binds-before-version class).
+ */
+export declare function handleEarlyArgs(argv: string[]): "help" | "version" | "start";
+export declare function mcpUsage(): string;
 export declare function isDirectMcpEntry(entry?: string): boolean;
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAgBpE,wBAAgB,WAAW,IAAI,SAAS,CAKvC;AAkBD,wBAAgB,gBAAgB,CAAC,KAAK,SAAkB,GAAG,OAAO,CAIjE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiBpE,wBAAgB,WAAW,IAAI,SAAS,CAKvC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAI5E;AAED,wBAAgB,QAAQ,IAAI,MAAM,CASjC;AA0CD,wBAAgB,gBAAgB,CAAC,KAAK,SAAkB,GAAG,OAAO,CAIjE"}

package/dist/mcp/index.js

@@ -19811,6 +19811,7 @@ function readConnectorTokens(name, profile = "default") {
 
 // src/cloud/http-storage.ts
 import {
+  ClientTransportConfigurationError,
   createHasnaHttpTransport,
   resolveCredential,
   resolveClientTransport as resolveSharedClientTransport
@@ -19900,6 +19901,27 @@ function assertConfigurationUnchanged(env, expected) {
     invalid();
 }
 
+// src/cloud/resolver-inputs.ts
+import {
+  clientTransportEnvKeys as clientTransportEnvKeys2,
+  credentialOverrideEnvKey,
+  credentialPointerEnvKey,
+  CREDENTIAL_PROFILE_ENV_KEY
+} from "@hasna/contracts/client";
+var CONTRACTS_AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+function isAmbientContactsEnv(env) {
+  if (typeof process !== "undefined" && env === process.env)
+    return true;
+  return env[CONTRACTS_AMBIENT_ENVIRONMENT] === true;
+}
+function contactsResolverCredentials(env, credentials = {}) {
+  const keychain = { ...credentials.keychain };
+  if (keychain.enabled === undefined && keychain.run === undefined) {
+    keychain.enabled = isAmbientContactsEnv(env);
+  }
+  return { ...credentials, keychain };
+}
+
 // src/cloud/http-storage.ts
 var RETIRED_CLIENT_SELECTOR_KEYS = [
   "HASNA_CONTACTS_STORAGE_MODE",
@@ -19935,37 +19957,44 @@ class ContactsClientConfigurationError extends Error {
     this.name = "ContactsClientConfigurationError";
   }
 }
-function unconfiguredResolution(resolution, issue2) {
+function unconfiguredResolution(issue2, resolution, warning = null) {
   return {
     transport: "unconfigured",
     baseUrl: null,
-    apiUrlSource: resolution.apiUrlSource,
-    apiKeyPresent: resolution.apiKeyPresent,
-    apiKeySource: resolution.apiKeySource,
-    apiKeyTier: resolution.apiKeyTier,
+    apiUrlSource: resolution?.apiUrlSource ?? null,
+    apiKeyPresent: resolution?.apiKeyPresent ?? false,
+    apiKeySource: resolution?.apiKeySource ?? null,
+    apiKeyTier: resolution?.apiKeyTier ?? null,
     configured: false,
     misconfigured: true,
     issue: issue2,
-    warning: null
+    warning
   };
 }
-function resolveContactsClientTransport(name, env = process.env) {
+function resolveContactsClientTransport(name, env = process.env, credentials = {}) {
   if (name !== "contacts") {
     throw new ContactsClientConfigurationError("CONTACTS_CLIENT_NAME_INVALID", "This resolver only accepts the contacts app slug.");
   }
   assertNoRetiredClientSelectors(env);
   const stamp = clientConfigurationStamp(env);
-  const resolution = resolveSharedClientTransport(name, env);
-  assertConfigurationUnchanged(env, stamp);
-  if (resolution.transport !== "http" || !resolution.baseUrl) {
-    const issue2 = resolution.misconfigured ? "The configured contacts API URL or credential is invalid or incomplete." : "HASNA_CONTACTS_API_URL and a resolvable contacts API key are required; no local fallback exists.";
-    return unconfiguredResolution(resolution, issue2);
+  let resolution;
+  try {
+    resolution = resolveSharedClientTransport(name, env, {
+      credentials: contactsResolverCredentials(env, credentials)
+    });
+  } catch (error2) {
+    assertConfigurationUnchanged(env, stamp);
+    if (error2 instanceof ClientTransportConfigurationError) {
+      return unconfiguredResolution(error2.message, null);
+    }
+    throw error2;
   }
+  assertConfigurationUnchanged(env, stamp);
   try {
     assertHttpsBaseUrl(resolution.baseUrl);
   } catch (error2) {
     return {
-      ...unconfiguredResolution(resolution, error2 instanceof Error ? error2.message : String(error2)),
+      ...unconfiguredResolution(error2 instanceof Error ? error2.message : String(error2), resolution),
       apiKeyPresent: resolution.apiKeyPresent
     };
   }
@@ -19979,7 +20008,7 @@ function resolveContactsClientTransport(name, env = process.env) {
     configured: true,
     misconfigured: false,
     issue: null,
-    warning: null
+    warning: resolution.warning
   };
 }
 function resourcePath(resource) {
@@ -20033,20 +20062,21 @@ function createStorageClient(name, transport) {
     }
   };
 }
-function resolveContactsStorageClient(name, env = process.env) {
-  const resolution = resolveContactsClientTransport(name, env);
+function resolveContactsStorageClient(name, env = process.env, credentials = {}) {
+  const resolution = resolveContactsClientTransport(name, env, credentials);
   if (!resolution.configured || !resolution.baseUrl) {
     throw new ContactsClientConfigurationError("CONTACTS_API_NOT_CONFIGURED", `${resolution.issue ?? "The contacts API client is not configured."} ` + "Configure HASNA_CONTACTS_API_URL and a contacts API key; the client will not read or create a local SQLite database.");
   }
   const baseUrl = resolution.baseUrl;
+  const chainOptions = contactsResolverCredentials(env, credentials);
   const request = async (method, path, body, opts) => {
     const stamp = clientConfigurationStamp(env);
     const snapshot = { ...env };
-    const current = resolveContactsClientTransport(name, snapshot);
+    const current = resolveContactsClientTransport(name, snapshot, chainOptions);
     if (!current.configured || current.baseUrl !== baseUrl) {
       throw new ContactsClientConfigurationError("CONTACTS_AUTHORITY_CHANGED", "Client authority changed or disappeared; construct a new client before sending data.");
     }
-    const credential = resolveCredential(name, snapshot);
+    const credential = resolveCredential(name, snapshot, chainOptions);
     if (!credential)
       throw new ContactsClientConfigurationError("CONTACTS_API_NOT_CONFIGURED", "No credential is available.");
     assertConfigurationUnchanged(env, stamp);
@@ -24678,6 +24708,37 @@ function registerContactsStorageTools(server) {
   });
 }
 
+// src/mcp/startup-gate.ts
+import {
+  completePointerCredential,
+  resolveCredential as resolveCredential2
+} from "@hasna/contracts/client";
+var MCP_REFUSAL_PREFIX = "contacts-mcp: refusing to start \u2014";
+var MCP_REFUSAL_HINT = "The MCP server never serves tools without a contacts credential and never reads or creates a local store; " + "configure the credential and restart contacts-mcp.";
+async function resolveMcpStartupGate(env = process.env, credentials = {}, options = {}) {
+  let issue2;
+  try {
+    const resolution = resolveContactsClientTransport("contacts", env, credentials);
+    if (resolution.configured) {
+      if (resolution.apiKeyTier !== "pointer") {
+        return { ok: true, apiUrlSource: resolution.apiUrlSource, apiKeySource: resolution.apiKeySource };
+      }
+      const chainOptions = contactsResolverCredentials(env, credentials);
+      const pointer = resolveCredential2("contacts", env, chainOptions);
+      if (!pointer || pointer.tier !== "pointer") {
+        throw new Error(`${resolution.apiKeySource ?? "HASNA_CONTACTS_API_KEY_REF"} resolved as a vault pointer but produced no pointer credential; this is a defect in the resolver.`);
+      }
+      const completed = await (options.completePointer ?? completePointerCredential)("contacts", pointer, env);
+      return { ok: true, apiUrlSource: resolution.apiUrlSource, apiKeySource: completed.source };
+    }
+    issue2 = `CONTACTS_API_NOT_CONFIGURED: ${resolution.issue ?? "The contacts API client is not configured."}`;
+  } catch (error2) {
+    issue2 = error2 instanceof Error ? error2.message : String(error2);
+  }
+  return { ok: false, message: `${MCP_REFUSAL_PREFIX} ${issue2}
+${MCP_REFUSAL_HINT}` };
+}
+
 // ../../node_modules/.bun/@modelcontextprotocol+sdk@1.30.0+2b91fc17bf64bdfd/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/mediaType.js
 var import_content_type = __toESM(require_content_type(), 1);
 function mediaTypeEssence(header) {
@@ -25434,8 +25495,39 @@ function buildServer() {
   registerContactsStorageTools(server);
   return server;
 }
+function handleEarlyArgs(argv) {
+  if (argv.includes("--help") || argv.includes("-h"))
+    return "help";
+  if (argv.includes("--version") || argv.includes("-V"))
+    return "version";
+  return "start";
+}
+function mcpUsage() {
+  return `usage: contacts-mcp                       MCP server over stdio (default)
+       contacts-mcp --http [--port <n>]   Streamable-HTTP dev server (loopback)
+       contacts-mcp --version             Print the version
+
+options:
+  --help, -h          show this help and exit
+  --version, -V       print the package version and exit
+`;
+}
 async function main() {
   const args = process.argv.slice(2);
+  const early = handleEarlyArgs(args);
+  if (early === "help") {
+    console.log(mcpUsage());
+    return;
+  }
+  if (early === "version") {
+    console.log(getServerVersion());
+    return;
+  }
+  const gate = await resolveMcpStartupGate();
+  if (!gate.ok) {
+    console.error(gate.message);
+    process.exit(1);
+  }
   if (isHttpMode(args)) {
     startMcpHttpServer({
       name: "contacts",
@@ -25461,6 +25553,8 @@ if (isDirectMcpEntry()) {
   });
 }
 export {
+  mcpUsage,
   isDirectMcpEntry,
+  handleEarlyArgs,
   buildServer
 };