In TypeScript, how do you add a property to an interface that an npm package exports, and what rules must the `declare module 'pkg'` block obey?

## What an augmentation actually is A module augmentation is nothing more exotic than interface merging pointed at somebody else's declaration space. Ordinarily, declarations merge only within one scope, and a module's declarations are sealed inside that module. `declare module '<specifier>'` opens that scope by name so your declarations land inside it: ```ts import { Session } from 'session-lib'; declare module 'session-lib' { interface Session { tenantId: string; } } function tenantOf(s: Session): string { return s.tenantId; // now type-checks } ``` The package's own `Session` interface and yours merge into one, and the merged shape is what *every* consumer in the compilation sees — not only this file. ## The file must be a module The containing file needs a top-level `import` or `export`; add `export {}` if it has neither. This is not ceremony. In a script file, `declare module 'session-lib' { ... }` means something entirely different: it declares an *ambient module* — a from-scratch description of a module that has no types of its own. Same syntax, opposite meaning. In a module file it augments; in a script file it declares. Getting this wrong is the classic failure where the package's real types appear to vanish or the additions appear to be ignored. ## The specifier must be the one that resolves You augment the module whose specifier you write, and it must resolve to the declaration you are targeting. If the interface you want lives in a sub-package or an internal entry point, the augmentation must name *that* specifier, not the umbrella one you happen to import from in application code. If the specifier does not resolve at all, the compiler reports an invalid module name in the augmentation. When an augmentation "does nothing", a mismatched specifier is the first thing to check, and reading the package's own type declarations to find where the interface is really declared is the way to settle it. ## What you may write inside Two restrictions come from the design: - **Only patches to existing declarations.** You cannot add new top-level declarations to the module through an augmentation. Adding members to an interface the module already exports is a patch; conjuring a brand-new exported entity is not. - **No default exports.** Augmentation works by exported name, and there is no name to merge against for a default export. If a library wants to be augmentable, it must expose named declarations. Beyond that, you are bound by ordinary merging rules. You can add members to an exported `interface`; you can add members to an exported `namespace`; and because an interface declaration merges with a class's instance type, you can add instance members to an exported class. You cannot merge into an exported `type` alias at all — aliases are closed, which is exactly why library authors who want extensibility publish interfaces. And you cannot change the type of a member that already exists: same-name, different-type is a merge conflict error, not an override. ## The file has to be in the program An augmentation only exists if its file is part of the compilation. A file that nothing imports and that the program does not otherwise include is invisible, and the additions silently do not apply. The two usual remedies are to import the augmentation file from somewhere in the app, or to keep it in a location the project already includes. (The mechanics of *which* files a project pulls in are a compiler-configuration topic in their own right; the point here is that an augmentation is not magically discovered.) ## Design consequences worth saying out loud Augmentation is global and unconditional. There is no way to scope it to one folder, one team, or one entry point: once the file is in the program, everyone's `Session` has `tenantId`, including code that has never heard of your feature. That is powerful for genuine cross-cutting extensions — a plugin ecosystem whose whole design is "packages contribute fields" — and hazardous when two packages augment the same interface with the same name and different types, which is a hard error somebody has to resolve. It is also, as always in TypeScript, only a claim. The types are erased, so declaring `tenantId: string` does not make the field exist; if the middleware that sets it did not run, you read `undefined` from a value the compiler swears is a `string`. Declaring such fields optional keeps the type honest and forces call sites to handle the case where the extension has not been applied. ## When to reach for something else If only your own code needs the extra field, a local type — an intersection at the call site, a wrapper, or a narrow accessor that returns the enriched shape — keeps the change visible and reversible. Reserve augmentation for cases where third-party code, or code you do not control, must see the enriched type.