feat!: API refactor

examples/openai/celest/functions/open_ai.dart

@@ -8,7 +8,7 @@ import 'package:celest_backend/models.dart';
 import 'package:chat_gpt_sdk/chat_gpt_sdk.dart';
 import 'package:chat_gpt_sdk/src/model/chat_complete/response/chat_choice.dart';
 
-import '../resources.dart';
+import '../generated/resources.dart';
 
 /// Creates an instance of the OpenAI client.
 OpenAI _createOpenAI(String token) => OpenAI.instance.build(
@@ -36,7 +36,7 @@ Future<String> openAIRequest({
   required String model,
   required String prompt,
   ModelParameters parameters = const ModelParameters(),
-  @Env.openAiToken required String openAiToken,
+  @env.openAiToken required String openAiToken,
 }) async {
   final openAI = _createOpenAI(openAiToken);
 

examples/openai/celest/generated/resources.dart

@@ -0,0 +1,14 @@
+// Generated by Celest. This file should not be modified manually, but
+// it can be checked into version control.
+// ignore_for_file: type=lint, unused_local_variable, unnecessary_cast, unnecessary_import
+
+library;
+
+import 'package:celest/celest.dart';
+
+@Deprecated('Use `env` instead.')
+typedef Env = env;
+
+abstract final class env {
+  static const openAiToken = EnvironmentVariable(name: r'OPEN_AI_TOKEN');
+}

packages/celest/analysis_options.yaml

@@ -6,6 +6,8 @@ analyzer:
     strict-inference: true
     strict-raw-types: true
   errors:
+    camel_case_types: ignore
+
     # To prevent issues publishing.
     depend_on_referenced_packages: error
     public_member_api_docs: warning

packages/celest/lib/celest.dart

@@ -11,6 +11,7 @@ export 'src/auth/auth_provider.dart';
 export 'src/config/env.dart';
 
 /// Core
+export 'src/core/annotations.dart';
 export 'src/core/cloud_widget.dart';
 export 'src/core/context.dart';
 export 'src/core/project.dart';

packages/celest/lib/fix_data.yaml

@@ -0,0 +1,13 @@
+version: 1
+transforms:
+  - title: "Change '@Context.user' to '@principal' for accessing user data"
+    date: 2024-05-28
+    element:
+      uris: ["celest.dart"]
+      field: user
+      inClass: Context
+    changes:
+      - kind: replacedBy
+        newElement:
+          uris: ["celest.dart"]
+          variable: principal

packages/celest/lib/http.dart

@@ -0,0 +1,12 @@
+/// HTTP annotations for Celest Functions.
+///
+/// See the [docs](https://celest.dev/docs/functions/http/customization) for
+/// usage and examples.
+library http;
+
+export 'src/functions/http/http.dart';
+export 'src/functions/http/http_error.dart';
+export 'src/functions/http/http_header.dart';
+export 'src/functions/http/http_method.dart';
+export 'src/functions/http/http_query.dart';
+export 'src/functions/http/http_status.dart';

packages/celest/lib/src/core/annotations.dart

@@ -0,0 +1,43 @@
+import 'package:meta/meta_meta.dart';
+
+/// Marks a function or library as a cloud API.
+///
+/// Celest Functions are written as normal Dart functions in the `celest/functions`
+/// folder of your project.
+///
+/// To turn a function into a cloud function, add the `@cloud` annotation:
+///
+/// ```dart
+/// // A helper function (not a cloud function).
+/// String greet(String name) => 'Hello, $name!';
+///
+/// // A cloud function which exposes the greeting logic.
+/// @cloud
+/// Future<String> sayHello(Person person) async {
+///  return greet(person.name);
+/// }
+/// ```
+///
+/// For more information, see [Creating functions](https://celest.dev/docs/functions/creating-functions).
+const cloud = _Cloud();
+
+@Target({TargetKind.function, TargetKind.library})
+final class _Cloud {
+  const _Cloud();
+}
+
+/// Marks an extension type definition as a custom implementation or its
+/// representation type.
+///
+/// Custom implementations can be used to redefine the behavior of a type
+/// in Celest by changing some aspects of its interface. The most common
+/// use case for custom implementations is to customize serialization logic
+/// for a type which you do not own.
+///
+/// See the [docs](https://celest.dev/docs/functions/data-types#custom-implementations) for more information.
+const customOverride = _CustomOverride();
+
+@Target({TargetKind.extensionType})
+final class _CustomOverride {
+  const _CustomOverride();
+}

packages/celest/lib/src/core/context.dart

@@ -1,34 +1,46 @@
 import 'package:celest/celest.dart';
 
+/// {@template celest.core.principal}
+/// A contextual reference to the principal ([User]) invoking a [CloudFunction].
+///
+/// For more information, see [Authorizing your functions](https://celest.dev/docs/functions/authorizing-functions).
+///
+/// ## Example
+///
+/// To inject a user into an `@authenticated` function:
+///
+/// ```dart
+/// @authenticated
+/// Future<void> sayHello({
+///   @principal required User user,
+/// }) async {
+///  print('Hello, ${user.displayName}!');
+/// }
+/// ```
+///
+/// If a user is injected to a `@public` or private function, then the
+/// user parameter must be nullable:
+///
+/// ```dart
+/// @public
+/// Future<void> sayHello({
+///   @principal User? user,
+/// }) async {
+///   print('Hello, ${user?.displayName ?? 'stranger'}!');
+/// }
+/// ```
+/// {@endtemplate}
+const principal = _UserContext();
+
+/// {@template celest.core.context}
 /// The context of a [CloudFunction] invocation.
-abstract final class Context {
-  /// A context reference to the [User] invoking a [CloudFunction].
-  ///
-  /// ## Example
-  ///
-  /// To inject a user into an `@authenticated` function:
-  ///
-  /// ```dart
-  /// @authenticated
-  /// Future<void> sayHello({
-  ///   @Context.user required User user,
-  /// }) async {
-  ///  print('Hello, ${user.displayName}!');
-  /// }
-  /// ```
-  ///
-  /// If a user is injected to a `@public` or private function, then the
-  /// user parameter must be nullable:
-  ///
-  /// ```dart
-  /// @public
-  /// Future<void> sayHello({
-  ///   @Context.user User? user,
-  /// }) async {
-  ///   print('Hello, ${user?.displayName ?? 'stranger'}!');
-  /// }
-  /// ```
-  static const user = _UserContext();
+/// {@endtemplate}
+final class Context {
+  const Context._();
+
+  /// {@macro celest.core.principal}
+  @Deprecated('Use @principal instead.')
+  static const Context user = principal;
 }
 
 final class _UserContext implements Context {

packages/celest/lib/src/functions/http/http.dart

@@ -0,0 +1,20 @@
+import 'package:celest/http.dart';
+import 'package:meta/meta_meta.dart';
+
+/// {@template celest.functions.http}
+/// HTTP configuration options for cloud functions.
+/// {@endtemplate}
+@Target({TargetKind.library, TargetKind.function})
+final class http {
+  /// {@macro celest.functions.http}
+  const http({
+    this.method = HttpMethod.post,
+    this.statusCode = HttpStatus.ok,
+  });
+
+  /// The HTTP method this function supports.
+  final HttpMethod method;
+
+  /// The status code returned for a successful response.
+  final HttpStatus statusCode;
+}

packages/celest/lib/src/functions/http/http_error.dart

@@ -0,0 +1,47 @@
+import 'package:meta/meta_meta.dart';
+
+/// {@template celest.http.http_error}
+/// Configures an HTTP error response for a cloud function.
+/// {@endtemplate}
+@Target({TargetKind.library, TargetKind.function})
+final class httpError {
+  /// {@macro celest.http.http_error}
+  const httpError(
+    this.statusCode,
+    this.type, [
+    this.type1,
+    this.type2,
+    this.type3,
+    this.type4,
+    this.type5,
+    this.type6,
+    this.type7,
+  ]);
+
+  /// The status code returned when any of the specified types are thrown.
+  final int statusCode;
+
+  /// The error type this configuration applies to.
+  final Type type;
+
+  /// Additional error type this configuration applies to.
+  final Type? type1;
+
+  /// Additional error type this configuration applies to.
+  final Type? type2;
+
+  /// Additional error type this configuration applies to.
+  final Type? type3;
+
+  /// Additional error type this configuration applies to.
+  final Type? type4;
+
+  /// Additional error type this configuration applies to.
+  final Type? type5;
+
+  /// Additional error type this configuration applies to.
+  final Type? type6;
+
+  /// Additional error type this configuration applies to.
+  final Type? type7;
+}

packages/celest/lib/src/functions/http/http_header.dart

@@ -0,0 +1,13 @@
+import 'package:meta/meta_meta.dart';
+
+/// {@template celest.http.http_header}
+/// An HTTP header key.
+/// {@endtemplate}
+@Target({TargetKind.parameter})
+final class httpHeader {
+  /// {@macro celest.http.http_header}
+  const httpHeader(this.name);
+
+  /// The name of the HTTP header.
+  final String name;
+}

packages/celest/lib/src/functions/http/http_method.dart

@@ -0,0 +1,17 @@
+/// Supported HTTP methods in Celest.
+extension type const HttpMethod._(String method) implements String {
+  /// `GET`
+  static const get = HttpMethod._('GET');
+
+  /// `POST`
+  static const post = HttpMethod._('POST');
+
+  /// `PUT`
+  static const put = HttpMethod._('PUT');
+
+  /// `DELETE`
+  static const delete = HttpMethod._('DELETE');
+
+  /// `PATCH`
+  static const patch = HttpMethod._('PATCH');
+}

packages/celest/lib/src/functions/http/http_query.dart

@@ -0,0 +1,13 @@
+import 'package:meta/meta_meta.dart';
+
+/// {@template celest.functions.http.http_query}
+/// An HTTP query parameter key.
+/// {@endtemplate}
+@Target({TargetKind.parameter})
+final class httpQuery {
+  /// {@macro celest.functions.http.http_query}
+  const httpQuery(this.name);
+
+  /// The name of the HTTP query parameter.
+  final String name;
+}