@typespec/http 0.41.0

package/dist/src/types.d.ts

@@ -0,0 +1,254 @@
+import { DiagnosticResult, Interface, ListOperationOptions, ModelProperty, Namespace, Operation, Program, Type } from "@typespec/compiler";
+/**
+ * @deprecated use `HttpOperation`. To remove in November 2022 release.
+ */
+export type OperationDetails = HttpOperation;
+export type HttpVerb = "get" | "put" | "post" | "patch" | "delete" | "head";
+export interface ServiceAuthentication {
+    /**
+     * Either one of those options can be used independently to authenticate.
+     */
+    options: AuthenticationOption[];
+}
+export interface AuthenticationOption {
+    /**
+     * For this authentication option all the given auth have to be used together.
+     */
+    schemes: HttpAuth[];
+}
+export type HttpAuth = BasicAuth | BearerAuth | ApiKeyAuth<ApiKeyLocation, string> | Oauth2Auth<OAuth2Flow[]>;
+export interface HttpAuthBase {
+    /**
+     * Id of the authentication scheme.
+     */
+    id: string;
+    /**
+     * Optional description.
+     */
+    description?: string;
+}
+/**
+ * Basic authentication is a simple authentication scheme built into the HTTP protocol.
+ * The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.
+ * For example, to authorize as demo / p@55w0rd the client would send
+ * ```
+ *  Authorization: Basic ZGVtbzpwQDU1dzByZA==
+ * ```
+ */
+export interface BasicAuth extends HttpAuthBase {
+    type: "http";
+    scheme: "basic";
+}
+/**
+ * Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.
+ * The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request.
+ * The client must send this token in the Authorization header when making requests to protected resources:
+ * ```
+ *   Authorization: Bearer <token>
+ * ```
+ */
+export interface BearerAuth extends HttpAuthBase {
+    type: "http";
+    scheme: "bearer";
+}
+type ApiKeyLocation = "header" | "query" | "cookie";
+/**
+ * An API key is a token that a client provides when making API calls. The key can be sent in the query string:
+ * ```
+ * GET /something?api_key=abcdef12345
+ * ```
+ *
+ * or as a request header
+ *
+ * ```
+ * GET /something HTTP/1.1
+ * X-API-Key: abcdef12345
+ * ```
+ *
+ * or as a cookie
+ *
+ * ```
+ * GET /something HTTP/1.1
+ * Cookie: X-API-KEY=abcdef12345
+ * ```
+ */
+export interface ApiKeyAuth<TLocation extends ApiKeyLocation, TName extends string> extends HttpAuthBase {
+    type: "apiKey";
+    in: TLocation;
+    name: TName;
+}
+/**
+ * OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.
+ * OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials.
+ * For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.
+ * For more information about OAuth 2.0, see oauth.net and RFC 6749.
+ */
+export interface Oauth2Auth<TFlows extends OAuth2Flow[]> extends HttpAuthBase {
+    type: "oauth2";
+    flows: TFlows;
+}
+export type OAuth2Flow = AuthorizationCodeFlow | ImplicitFlow | PasswordFlow | ClientCredentialsFlow;
+export type OAuth2FlowType = OAuth2Flow["type"];
+/**
+ * Authorization Code flow
+ */
+export interface AuthorizationCodeFlow {
+    type: "authorizationCode";
+    authorizationUrl: string;
+    tokenUrl: string;
+    refreshUrl?: string;
+    scopes: OAuth2Scope[];
+}
+/**
+ * Implicit flow
+ */
+export interface ImplicitFlow {
+    type: "implicit";
+    authorizationUrl: string;
+    refreshUrl?: string;
+    scopes: OAuth2Scope[];
+}
+/**
+ * Resource Owner Password flow
+ */
+export interface PasswordFlow {
+    type: "password";
+    authorizationUrl: string;
+    refreshUrl?: string;
+    scopes: OAuth2Scope[];
+}
+/**
+ * Client credentials flow
+ */
+export interface ClientCredentialsFlow {
+    type: "clientCredentials";
+    tokenUrl: string;
+    refreshUrl?: string;
+    scopes: OAuth2Scope[];
+}
+export interface OAuth2Scope {
+    value: string;
+    description?: string;
+}
+export type OperationContainer = Namespace | Interface;
+export type OperationVerbSelector = (program: Program, operation: Operation) => HttpVerb | undefined;
+export interface OperationParameterOptions {
+    verbSelector?: OperationVerbSelector;
+}
+export interface RouteOptions {
+    [prop: string]: any;
+    paramOptions?: OperationParameterOptions;
+}
+export interface RouteResolutionOptions extends RouteOptions {
+    listOptions?: ListOperationOptions;
+}
+export interface RouteProducerResult {
+    segments: string[];
+    parameters: HttpOperationParameters;
+}
+export type RouteProducer = (program: Program, operation: Operation, parentSegments: string[], overloadBase: HttpOperation | undefined, options: RouteOptions) => DiagnosticResult<RouteProducerResult>;
+export interface HeaderFieldOptions {
+    type: "header";
+    name: string;
+    format?: "csv";
+}
+export interface QueryParameterOptions {
+    type: "query";
+    name: string;
+    format?: "multi" | "csv";
+}
+export interface PathParameterOptions {
+    type: "path";
+    name: string;
+}
+export type HttpOperationParameter = (HeaderFieldOptions | QueryParameterOptions | PathParameterOptions) & {
+    param: ModelProperty;
+};
+/**
+ * Represent the body information for an http request.
+ *
+ * @note the `type` must be a `Model` if the content type is multipart.
+ */
+export interface HttpOperationRequestBody extends HttpOperationBody {
+    /**
+     * If the body was explicitly set as a property. Correspond to the property with `@body`
+     */
+    parameter?: ModelProperty;
+}
+export interface HttpOperationParameters {
+    parameters: HttpOperationParameter[];
+    body?: HttpOperationRequestBody;
+    /** @deprecated use @see body.type */
+    bodyType?: Type;
+    /** @deprecated use @see body.property */
+    bodyParameter?: ModelProperty;
+}
+export interface HttpService {
+    namespace: Namespace;
+    operations: HttpOperation[];
+}
+export interface HttpOperation {
+    /**
+     * Route path
+     */
+    path: string;
+    /**
+     * Path segments
+     */
+    pathSegments: string[];
+    /**
+     * Route verb.
+     */
+    verb: HttpVerb;
+    /**
+     * Parent type being the interface, namespace or global namespace.
+     */
+    container: OperationContainer;
+    /**
+     * Parameters.
+     */
+    parameters: HttpOperationParameters;
+    /**
+     * Responses.
+     */
+    responses: HttpOperationResponse[];
+    /**
+     * Operation type reference.
+     */
+    operation: Operation;
+    /**
+     * Overload this operation
+     */
+    overloading?: HttpOperation;
+    /**
+     * List of operations that overloads this one.
+     */
+    overloads?: HttpOperation[];
+}
+export interface RoutePath {
+    path: string;
+    shared: boolean;
+}
+export type StatusCode = `${number}` | "*";
+export interface HttpOperationResponse {
+    statusCode: StatusCode;
+    type: Type;
+    description?: string;
+    responses: HttpOperationResponseContent[];
+}
+export interface HttpOperationResponseContent {
+    headers?: Record<string, ModelProperty>;
+    body?: HttpOperationBody;
+}
+export interface HttpOperationBody {
+    /**
+     * Content types.
+     */
+    contentTypes: string[];
+    /**
+     * Type of the operation body.
+     */
+    type: Type;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extract params to be interpolated(Wrapped in '{' and '}'}) from a path/url.
+ * @param path Path/Url
+ *
+ * @example "foo/{name}/bar" -> ["name"]
+ */
+export declare function extractParamsFromPath(path: string): string[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D"}

package/dist/src/utils.js

@@ -0,0 +1,11 @@
+/**
+ * Extract params to be interpolated(Wrapped in '{' and '}'}) from a path/url.
+ * @param path Path/Url
+ *
+ * @example "foo/{name}/bar" -> ["name"]
+ */
+export function extractParamsFromPath(path) {
+    var _a, _b;
+    return (_b = (_a = path.match(/\{\w+\}/g)) === null || _a === void 0 ? void 0 : _a.map((s) => s.slice(1, -1))) !== null && _b !== void 0 ? _b : [];
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;;IAChD,OAAO,MAAA,MAAA,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,0CAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,mCAAI,EAAE,CAAC;AAClE,CAAC"}

package/dist/src/validate.d.ts

@@ -0,0 +1,3 @@
+import { Program } from "@typespec/compiler";
+export declare function $onValidate(program: Program): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/src/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,QAM3C"}

package/dist/src/validate.js

@@ -0,0 +1,9 @@
+import { getAllHttpServices } from "./operations.js";
+export function $onValidate(program) {
+    // Pass along any diagnostics that might be returned from the HTTP library
+    const [, diagnostics] = getAllHttpServices(program);
+    if (diagnostics.length > 0) {
+        program.reportDiagnostics(diagnostics);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/src/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,0EAA0E;IAC1E,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE;QAC1B,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;KACxC;AACH,CAAC"}

package/lib/auth.tsp

@@ -0,0 +1,185 @@
+namespace TypeSpec.Http;
+
+@doc("Authentication type")
+enum AuthType {
+  @doc("HTTP")
+  http,
+
+  @doc("API key")
+  apiKey,
+
+  @doc("OAuth2")
+  oauth2,
+
+  @doc("OpenID connect")
+  openIdConnect,
+}
+
+/**
+ *  Basic authentication is a simple authentication scheme built into the HTTP protocol.
+ *  The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.
+ *  For example, to authorize as demo / `p@55w0rd` the client would send
+ *  ```
+ *  Authorization: Basic ZGVtbzpwQDU1dzByZA==
+ *  ```
+ */
+model BasicAuth {
+  @doc("Http authentication")
+  type: AuthType.http;
+
+  @doc("basic auth scheme")
+  scheme: "basic";
+}
+
+/**
+ * Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.
+ * The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request.
+ * The client must send this token in the Authorization header when making requests to protected resources:
+ * ```
+ *   Authorization: Bearer <token>
+ * ```
+ */
+model BearerAuth {
+  @doc("Http authentication")
+  type: AuthType.http;
+
+  @doc("bearer auth scheme")
+  scheme: "bearer";
+}
+
+@doc("Describes the location of the API key")
+enum ApiKeyLocation {
+  @doc("API key is a header value")
+  header,
+
+  @doc("API key is a query parameter")
+  query,
+
+  @doc("API key is found in a cookie")
+  cookie,
+}
+
+/**
+ * An API key is a token that a client provides when making API calls. The key can be sent in the query string:
+ * ```
+ * GET /something?api_key=abcdef12345
+ * ```
+ *
+ * or as a request header
+ *
+ * ```
+ * GET /something HTTP/1.1
+ * X-API-Key: abcdef12345
+ * ```
+ *
+ * or as a cookie
+ *
+ * ```
+ * GET /something HTTP/1.1
+ * Cookie: X-API-KEY=abcdef12345
+ * ```
+ */
+model ApiKeyAuth<TLocation extends ApiKeyLocation, TName extends string> {
+  @doc("API key authentication")
+  type: AuthType.apiKey;
+
+  @doc("location of the API key")
+  in: TLocation;
+
+  @doc("name of the API key")
+  name: TName;
+}
+
+/**
+ * OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.
+ * OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials.
+ * For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.
+ * For more information about OAuth 2.0, see oauth.net and RFC 6749.
+ */
+model OAuth2Auth<TFlows extends OAuth2Flow[]> {
+  @doc("OAuth2 authentication")
+  type: AuthType.oauth2;
+
+  @doc("Supported OAuth2 flows")
+  flows: TFlows;
+}
+
+@doc("Describes the OAuth2 flow type")
+enum OAuth2FlowType {
+  @doc("authorization code flow")
+  authorizationCode,
+
+  @doc("implcit flow")
+  implicit,
+
+  @doc("password flow")
+  password,
+
+  @doc("client credential flow")
+  clientCredentials,
+}
+
+alias OAuth2Flow = AuthorizationCodeFlow | ImplicitFlow | PasswordFlow | ClientCredentialsFlow;
+
+@doc("Authorization Code flow")
+model AuthorizationCodeFlow {
+  @doc("authorization code flow")
+  type: OAuth2FlowType.authorizationCode;
+
+  @doc("the authorization URL")
+  authorizationUrl: string;
+
+  @doc("the token URL")
+  tokenUrl: string;
+
+  @doc("the refresh URL")
+  refreshUrl?: string;
+
+  @doc("list of scopes for the credential")
+  scopes: string[];
+}
+
+@doc("Implicit flow")
+model ImplicitFlow {
+  @doc("implicit flow")
+  type: OAuth2FlowType.implicit;
+
+  @doc("the authorization URL")
+  authorizationUrl: string;
+
+  @doc("the refresh URL")
+  refreshUrl?: string;
+
+  @doc("list of scopes for the credential")
+  scopes: string[];
+}
+
+@doc("Resource Owner Password flow")
+model PasswordFlow {
+  @doc("password flow")
+  type: OAuth2FlowType.password;
+
+  @doc("the authorization URL")
+  authorizationUrl: string;
+
+  @doc("the refresh URL")
+  refreshUrl?: string;
+
+  @doc("list of scopes for the credential")
+  scopes: string[];
+}
+
+@doc("Client credentials flow")
+model ClientCredentialsFlow {
+  @doc("client credential flow")
+  type: OAuth2FlowType.clientCredentials;
+
+  @doc("the token URL")
+  tokenUrl: string;
+
+  @doc("the refresh URL")
+  refreshUrl?: string;
+
+  @doc("list of scopes for the credential")
+  scopes: string[];
+}